openbom api specification document€¦ · openbom api specification document. index o ve rvi e w...

OpenBOM API Specification Document

Index Overview

Methods 1. Login 2. List BOMs 3. List Order BOMs 4. List Catalogs 5. List Property tables 6. Get specific bom document 7. Get specific catalog document 8. Get specific property table document 9. Update bom document property value 10. Update catalog document property value 11. Find BOM documents by parameters

Structures Bom item in boms listing array Bom document Catalog item in catalogs listing array Catalog document Property table item in property tables listing array Property table document

Glossary Conventions Status Codes

Overview The OpenBOM API allows developers to programmatically access data stored in the OpebBOM user account.

1. Each developer will need to get application key from OpenBOM and use it with each and every request to OpenBOM’s API. An API Key is required to be sent as part of every request to the OpenBOM API, in the form of an X-OpenBOM-AppKey request header. Developers must send requests to get application key to [email protected]

2. In addition, access token must be provided in every request, except for the /login API.

(See below: Login)

3. The OpenBOM API will only respond to secured communication done over HTTPS. HTTP requests will be sent a 301 redirect to corresponding HTTPS resources.

4. The response to every request is sent in JSON format, with the content-type header set

appropriately. In case the API request results in an error, it is represented by an "error": {} key in the JSON response.

5. The request method (verb) determines the nature of action you intend to perform. A

request made using the GET method implies that you want to fetch something from OpenBOM, and POST implies you want to save something new to OpenBOM.

6. The API calls will respond with appropriate HTTP status codes for all requests.

7. To prevent abuse, OpenBOM imposes rate limits on all incoming requests, in general 5

requests per second is the top limit (Subject to changes in the future). 429 response status code will be returned when limit is reached.

mailto:[email protected]

Methods

1. Login Authenticate the user with the system and obtain the access token. Access token, received in response, will be used in all subsequent requests as required parameter.

Request

Method URL

POST /login

Type Params Values

HEAD

HEAD

POST

content-type

X-OpenBOM-AppKey

JSON Object:{

username:...

password:...

}

string - application/json

string

X-OpenBOM-AppKey

X-OpenBOM-AppKey is the application key that the developer received from OpenBOM upon email request and must be sent with all client requests. The application key helps the server to validate the request source.

Example: curl -X POST \ https://developer-api.openbom.com/login \ -H 'content-type: application/json' \ -H 'x-openbom-appkey: developerappkey' \ -d '{"username":"[email protected]","password":"hardtoguess"}'

Response

Status Response

200 {

"access_token": <access_token>, "refresh_token": <auth_key>, "token_type": ”Bearer”, "expires_in": 86400 }

access_token (string) - all further API calls must have this key in request header X-OpenBOM-AccessToken

400 {"error":"Parameter [\"username\"] not found."}

401 {"error":"Unable to authenticate user[user@email]"}

403 {"error":""Missing or invalid developer application key[app_key]""}

2. List BOMs Get all boms accessible by the user

Request

Method URL

GET /boms

Type Params Values

HEAD X-OpenBOM-AppKey string

HEAD X-OpenBOM-AccessToken string

X-OpenBOM-AppKey

X-OpenBOM-AppKey is the application key that developer received from OpenBOM X-OpenBOM-AccessToken

X-OpenBOM-AccessToken value is the value of the access_token parameter that was given in response to /login

Example curl -X GET \ https://developer-api.openbom.com/boms \ -H 'x-openbom-accesstoken: eyJraWQiOiJjSVAyRU1NYUZuSnFhSkhUaD...' \ -H 'x-openbom-appkey: developerappkey'

Response

Status Response

200 Response will be an object containing the list of bom documents properties (array) . Each item in the boms listing array has the following structure. { "nodeId": 0, "bomId": "0", "id": "0", "name": "", "nameuri": "", "user": "", "status": "", "permissionString": "", "permission": 0, "modifiedBy": "", "modified": 0, "bomPartNumber": "", "productionBatch": false, "released": false }

An example response is:- [

{

"nodeId": 29290, "bomId": "49c6f1f3-7006-48fc-86f1-f3700628fcff", "id": "49c6f1f3-7006-48fc-86f1-f3700628fcff", "name": "R2D2_2", "nameuri": null, "user": "user@email", "status": "active", "permissionString": "w", "permission": 7, "modifiedBy": "user@email", "modified": 1518126594320, "bomPartNumber": "R2D2_2", "productionBatch": false, "released": false },

{

"nodeId": 34669, "bomId": "bec849c7-f55b-4dc8-8849-c7f55bddc846", "id": "bec849c7-f55b-4dc8-8849-c7f55bddc846", "name": "Controller BOM", "nameuri": null, "user": "user@email", "status": "active", "permissionString": "w", "permission": 7, "modifiedBy": "user@email", "modified": 1518124259396, "bomPartNumber": "Controller BOM", "productionBatch": false, "released": true }

]

401 {"error":"Missing or invalid access token."}

403 {"error":"Missing or invalid developer application key[app_key]"}

500 {"error":"Something went wrong. Please try again later."}

3. List Order BOMs Get all order boms accessible by the user

Request

Method URL

GET /orderboms

Type Params Values

HEAD

HEAD

X-OpenBOM-AppKey

X-OpenBOM-AccessToken

string

string


X-OpenBOM-AccessTokenAppKey value is the value of the access_token parameter that was given in response to /login

Example curl -X GET \ https://developer-api.openbom.com/orderboms \ -H 'x-openbom-accesstoken: eyJraWQiOiJjSVAyRU1NYUZuSnFhSkhUaD...' \ -H 'x-openbom-appkey: developerappkey'

Response

Status Response

200 Response will be an object containing the list of order bom documents properties (array) . Each item in the order boms listing array has the following structure. { "nodeId": 0,

"bomId": "0", "id": "0", "name": "", "nameuri": "", "user": "", "status": "", "permissionString": "", "permission": 0, "modifiedBy": "", "modified": 0, "bomPartNumber": "", "productionBatch": false, "released": false }


{

"nodeId": 7620, "bomId": "4c1d540b-7117-4c87-9d54-0b71177c8706", "id": "4c1d540b-7117-4c87-9d54-0b71177c8706", "name": "Order 1 Controller BOM", "nameuri": null, "user": "user@email", "status": "active", "permissionString": "w", "permission": 7, "modifiedBy": "user@email", "modified": 1518124271145, "productionBatch": true, "released": false },

{

"nodeId": 7619, "bomId": "d767cc53-e4a2-4351-a7cc-53e4a2d35122", "id": "d767cc53-e4a2-4351-a7cc-53e4a2d35122", "name": "Order 1 calc failure", "nameuri": null, "user": "user@email", "status": "active", "permissionString": "w", "permission": 7,

"modifiedBy": "user@email", "modified": 1518124230864, "productionBatch": true, "released": false }

]




4. List Catalogs Get all catalogs accessible by the user

Request

Method URL

GET /catalogs

Type Params Values

HEAD

HEAD

X-OpenBOM-AppKey


string

string

X-OpenBOM-AppKey



Example curl -X GET \ https://developer-api.openbom.com/catalogs \ -H 'x-openbom-accesstoken: eyJraWQiOiJjSVAyRU1NYUZuSnFhSkhUaD...' \ -H 'x-openbom-appkey: developerappkey'

Response

Status Response

200 Response will be an object containing the list of catalog documents properties (array) . Each item in the catalogs listing array has the following structure. {

"nodeId": 0, "itemsId": "0", "id": "0", "name": "", "user": "", "status": "", "permissionString": "", "permission": 0, "modifiedBy": "", "modified": 0 }


{

"nodeId": 43557, "itemsId": "338c9e50-fe66-4a17-8c9e-50fe66ea17b5", "id": "338c9e50-fe66-4a17-8c9e-50fe66ea17b5", "name": "Items", "user": "user@email", "status": "active", "permissionString": "w", "permission": 7, "modifiedBy": "user@email", "modified": 1518127000879 },

{

"nodeId": 7048, "itemsId": "4b54c2b4-49aa-4a71-94c2-b449aa6a7158", "id": "4b54c2b4-49aa-4a71-94c2-b449aa6a7158", "name": "t4", "user": "user@email", "status": "active", "permissionString": "w", "permission": 7, "modifiedBy": "user@email", "modified": 1518107206291 }

]




5. List Property tables Get all property tables accessible by the user

Request

Method URL

GET /propertytables

Type Params Values

HEAD

HEAD

X-OpenBOM-AppKey


string

string

X-OpenBOM-AppKey



Example curl -X GET \ https://developer-api.openbom.com/propertytables \ -H 'x-openbom-accesstoken: eyJraWQiOiJjSVAyRU1NYUZuSnFhSkhUaD...' \ -H 'x-openbom-appkey: developerappkey'

Response

Status Response

200 Response will be an object containing the list of property tables documents properties (array) . Each item in the property tables listing array has the following structure. {

"_id": "", "id": "", "uri": "", "name": "", "createdBy": "", "updatedBy": "", "created": "", "updated": "", "private": false }


{

"_id": "64c4ff25-eed6-4c8f-84ff-25eed6bc8fd2", "id": "64c4ff25-eed6-4c8f-84ff-25eed6bc8fd2", "uri": "urn:openbom:name:user%email:props%20table", "name": "props table", "createdBy": "user@email", "updatedBy": null, "created": "2017-02-16T04:33:55.787Z", "updated": "2017-02-16T04:33:55.788Z", "private": false },

{

"_id": "53064d1a-8330-4a9a-864d-1a8330aa9a0e", "id": "53064d1a-8330-4a9a-864d-1a8330aa9a0e", "uri": "urn:openbom:name:user%40email:test1", "name": "test1", "createdBy": "user@email", "updatedBy": null, "created": "2017-08-25T13:31:28.387Z", "updated": "2017-08-25T13:31:28.388Z", "private": false }

]




6. Get specific bom document Receive the json representation of the bom document stored in openbom.

Request

Method URL

GET /bom/<bomId>

Type Params Values

HEAD

HEAD

URL_PARAM

X-OpenBOM-AppKey


<bomId>

string

string

string

X-OpenBOM-AppKey


X-OpenBOM-AccessToken value is the value of the access_token parameter that was given in

response to /login <bomId>

The id of the bom document to retrieve. Can be taken from listing response.

Example curl -X GET \ http://developer-api.openbom.com/bom/49c6f1f3-7006-48fc-86f1-f3700628fcff \ -H 'x-openbom-accesstoken: eyJraWQiOiJjSVAyRU...' \ -H 'x-openbom-appkey: developerappkey'

Response

Status Response

200 Response will be a json object representing bom document.

Refer to Structures section.




7. Get specific catalog document Receive the json representation of the catalog document stored in openbom.

Request

Method URL

GET /catalog/<catalogId>

Type Params Values

HEAD X-OpenBOM-AppKey string

HEAD

URL_PARAM


<catalogId>

string

string

X-OpenBOM-AppKey


X-OpenBOM-AccessToken value is the value of the access_token parameter that was given in response to /login <catalogId>

The id of the catalog document to retrieve. Can be taken from listing response.

Example curl -X GET \ http://developer-api.openbom.com/catalog/338c9e50-fe66-4a17-8c9e-50fe66ea17b5\ -H 'x-openbom-accesstoken: eyJraWQiOiJjSVAyRU...' \ -H 'x-openbom-appkey: developerappkey'

Response

Status Response

200 Response will be a json object representing catalog document.





8. Get specific property table document Receive the json representation of the property table document stored in OpenBOM.

Request

Method URL

GET /propertytable/<propertyTableId>

Type Params Values

HEAD

HEAD

URL_PARAM

X-OpenBOM-AppKey


<propertyTableId>

string

string

string

X-OpenBOM-AppKey


X-OpenBOM-AccessToken value is the value of the access_token parameter that was given in response to /login <propertyTableId>

The id of the property table document to retrieve. Can be taken from listing response.

Example curl -X GET \ http://developer-api.openbom.com/propertytable/64c4ff25-eed6-4c8f-84ff-25eed6bc8fd2\ -H 'x-openbom-accesstoken: eyJraWQiOiJjSVAyRU...' \ -H 'x-openbom-appkey: developerappkey'

Response

Status Response

200 Response will be a json array of objects representing items inside property table document.


Example response is: [ { "_id": "08f5562f-76af-42eb-b556-2f76aff2eb28", "id": "08f5562f-76af-42eb-b556-2f76aff2eb28", "uri": "urn:openbom:name:user%40email:prop1",

"name": "prop1", "sourcePropertyId": null, "privateTableId": "64c4ff25-eed6-4c8f-84ff-25eed6bc8fd2", "publicProperty": false, "status": "A", "datatype": "N", "source": "U", "created_by": "user@email", "created": "2017-02-16T04:34:08.135Z", "updated": "2017-02-16T04:34:08.138Z" }, { "_id": "763e1cd6-2e2e-46ac-be1c-d62e2e46acec", "id": "763e1cd6-2e2e-46ac-be1c-d62e2e46acec", "uri": "urn:openbom:name:user%40email:prop2", "name": "prop2", "sourcePropertyId": null, "privateTableId": "64c4ff25-eed6-4c8f-84ff-25eed6bc8fd2", "publicProperty": false, "status": "A", "datatype": "N", "source": "U", "created_by": "user@email", "created": "2017-02-16T04:34:15.937Z", "updated": "2017-02-16T04:34:15.939Z" } ]




9. Update bom document property value Updates specific property value, for specific part number in specified bom document.

Request

Method URL

POST /bom/<bomId>/propertyvalue

Type Params Values

HEAD

HEAD

URL_PARAM

POST

X-OpenBOM-AppKey


<bomId>

<json_params>

{

"partNumberPropertyName":"", "partNumber":"", "propertyName":"", "propertyValue":""

}

string

string

string

string

X-OpenBOM-AppKey


X-OpenBOM-AccessToken value is the value of the access_token parameter that was given in response to /login <bomId>

The id of the bom document to retrieve. Can be taken from listing response.

<json_params>

{

"partNumberPropertyName":"Part Number", //Name of the property for part numbers

"partNumber":"Centre Leg Assembly", //Actual item’s part number to identify the row in the document

"propertyName":"Quantity", //Name of the property to be updated "propertyValue":"25" //New Value of the property }

Example curl -X POST \ http://developer-api.openbom.com/bom/49c6f1f3-7006-48fc-86f1-f3700628fcff/propertyvalue \ -H 'x-openbom-accesstoken: eyJraWQiOiJjSVAyRU...' \ -H 'x-openbom-appkey: developerappkey'' \ -d '{

"partNumberPropertyName":"Part Number", "partNumber":"Centre Leg Assembly", "propertyName":"Quantity", "propertyValue":"25"

}'

Response

Status Response

200 {"message": "property value updated."}




10. Update catalog document property value Updates specific property value, for specific part number in specified catalog document.

Request

Method URL

POST /catalog/<catalogId>/propertyvalue

Type Params Values

HEAD

HEAD

X-OpenBOM-AppKey


string

string

HEAD

URL_PARAM

POST

Content-Type

<catalogId>

<json_params>

{

"partNumberPropertyName":"", "partNumber":"", "propertyName":"", "propertyValue":""

}

string

string

X-OpenBOM-AppKey


X-OpenBOM-AccessToken value is the value of the access_token parameter that was given in response to /login Content-Type

Content-Type value application/json <catalogId>

The id of the catalog document to update. Can be taken from listing response. <json_params>

{

"partNumberPropertyName":"Part Number", //Name of the property for part numbers

"partNumber":"Centre Leg Assembly", //Actual item’s part number to identify the row in the document

"propertyName":"Quantity", //Name of the property to be updated "propertyValue":"25" //New Value of the property }

Example curl -X POST \ http://developer-api.openbom.com/catalog/338c9e50-fe66-4a17-8c9e-50fe66ea17b5/propertyvalue \ -H 'content-type: application/json' \ -H 'x-openbom-accesstoken: eyJraWQiOiJjSVAyRU...' \ -H 'x-openbom-appkey: developerappkey'' \ -d '{

"partNumberPropertyName":"Part Number", "partNumber":"PN124", "propertyName":"Quantity On Hand",

"propertyValue":"14" }'

Response

Status Response

200 {"message": "property value updated."}




11. Find BOM documents by parameters Finds BOM documents by specific parameters.

Request

Method URL

POST /boms/byparams

Type Params Values

HEAD

HEAD

HEAD

POST

X-OpenBOM-AppKey


Content-Type

<json_params>

{

"name":"" }

string

string

string

X-OpenBOM-AppKey

X-OpenBOM-AppKey is the application key that developer received from OpenBOM


X-OpenBOM-AccessToken value is the value of the access_token parameter that was given in response to /login Content-Type

Content-Type value application/json <json_params>

Key value pairs in JSON form. Keys can be one or all of: name, bomPartNumber

Example curl -X POST \ https://developer-api.openbom.com/boms/byparams \ -H 'content-type: application/json' \ -H 'x-openbom-accesstoken: eyJraWQiOiJjSVAyRU...' \ -H 'x-openbom-appkey: developerappkey' \ -d '{

"name":"somebomname" }'

Response

Status Response

200 Partial example response, list of matching BOM documents: [ { "id": "ef9a204a-a8fe-48ed-9a20-4aa8fef8ede3", "type": "bom", "partNumber": "bompartnumber", "name": "somebomname", "modifiedDate": "07 Aug 2018; 15:48:27 GMT", "createdDate": "07 Aug 2018; 15:47:33 GMT", "modifiedBy": "user@email", "createdBy": "user@email", "columns": [ "Part Number", "Thumbnail image", "Description", "Cost", "Quantity" ],

"cells": [ [ "part1", null, "desc", 2, 1 ] ], "totalCells": [ [ "", "", "", "", 1 ] ] } ]




Structures

1. BOM item in boms listing array { "nodeId": 0, "bomId": "0", "id": "0", "name": "", "nameuri": "", "user": "", "status": "", "permissionString": "", "permission": 0, "modifiedBy": "", "modified": 0, "bomPartNumber": "", "productionBatch": false, "released": false }

2. BOM document

{ "id": "ef9a204a-a8fe-48ed-9a20-4aa8fef8ede3", //The Id of the bom document "type": "bom", // the type will always have the value of “bom” "partNumber": "somebomname", // part number for this bom document "name": "somebomname", // the name of the bom document "modifiedDate": "07 Aug 2018; 15:48:27 GMT", // date when bom was modified "createdDate": "07 Aug 2018; 15:47:33 GMT", // date when bom was created "modifiedBy": "user@email", // user that modified this document "createdBy": "user@email", // user that created this document "columns": [ // Array of all column names in bom document, "Part Number", "Thumbnail image", "Description", "Cost", "Quantity" ], "cells": [ // Array of arrays representing tabular data, order is according to columns array [ "part1", null, "part 1 description", 2, 1 ],

[ "part2", null, "part 2 description", 2, 1 ] ], "totalCells": [ // Array of total values for each column [ "", "", "", "", 2 ] ] }

3. Catalog item in catalogs listing array { "nodeId": 0, "itemsId": "0", "id": "0", "name": "", "user": "", "status": "", "permissionString": "", "permission": 0, "modifiedBy": "", "modified": 0 }

4. Catalog document { "id": "",

"type": "", "name": "", "modifiedDate": "", "createdDate": "", "modifiedBy": "", "createdBy": "", "columns": [], "cells": [[],[]] }

5. Property table item in property tables listing array TBD

6. Property table document

Glossary

Conventions ● Client - Client application. ● Status - HTTP status code of response. ● All the possible responses are listed under ‘Responses’ for each method. Only one of them

is issued per request server. ● All response are in JSON format. ● All request parameters are mandatory unless explicitly marked as [optional] ● The type of values accepted for a request parameter are shown the the values column like

this [10|<any number>] .The | symbol means OR. If the parameter is [optional], the default value is shown in blue bold text, as 10 is written in [10|<any number>].

Status Codes All status codes are standard HTTP status codes. The below ones are used in this API. 2XX - Success of some kind 4XX - Error occurred in client’s part 5XX - Error occurred in server’s part

Status Code Description

200 OK

201 Created

202 Accepted (Request accepted, and queued for execution)

400 Bad request

401 Authentication failure

403 Forbidden

404 Resource not found

405 Method Not Allowed

409 Conflict

412 Precondition Failed

413 Request Entity Too Large

429 Too Many Requests

500 Internal Server Error

501 Not Implemented

503 Service Unavailable

openbom api specification document€¦ · openbom api specification document. index o ve rvi e w...

Documents