OpenBOM REST API v1

 

 

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

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 openbom user account.

  1. Each developer will needs 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 support@openbom.com[a]
  1. In addition, access token must be provided in every request, but to /login API. (See below: Login)
  1. The OpenBOM API will only respond to secured communication done over HTTPS. HTTP requests will be sent a 301 redirect to corresponding HTTPS resources.
  1. Response to every request is sent in JSON format. In case the API request results in an error, it is represented by an “error”: {} key in the JSON response.
  1. 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.
  1. The API calls will respond with appropriate HTTP status codes for all requests.
  1. To prevent abuse, OpenBOM imposes rate limits on all incoming requests, in general 5 concurrent requests is the top limit (Subject to changes in the future)

Methods

1. Login

Authenticate the user with the system and obtain the access token

Request

 

Method

URL            

POST

/login

 

Type

Params

Values

HEAD

POST

POST

X-OpenBOM-AppKey

username

password

string

string

string

X-OpenBOM-AppKey

 X-OpenBOM-AppKey  is the application key that 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”:”user@email.tld”,”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

HEAD

X-OpenBOM-AppKey

X-OpenBOM-AccessToken

string

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-AccessToken

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

}

An example response is:-

[

    {

        “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

    }

]

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.”}

4. List Catalogs

Get all catalogs accessible by the user

Request

 

Method

URL            

GET

/catalogs

 

Type

Params

Values

HEAD

HEAD

X-OpenBOM-AppKey

X-OpenBOM-AccessToken

string

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/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

}

An example response is:-

[

    {

        “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

    }

]

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.”}

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

X-OpenBOM-AccessToken

string

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/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

}

An example response is:-

[

    {

        “_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

    }

]

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.”}

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

X-OpenBOM-AccessToken

<bomId>

string

string

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

<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.

Partial example response is:-

{

    “_id“: “49c6f1f3-7006-48fc-86f1-f3700628fcff“,

    “id“: “49c6f1f3-7006-48fc-86f1-f3700628fcff“,

    “sourceId“: “H:\\Models\\SW\\R2D2\\R2D2_2.SLDASM“,

    “name“: “R2D2_2“,

    “nameuri“: “urn:openbom:name:user%40email:r2d2_2“,

    “status“: “A”,

    “copyId“: null,

    “data“: {

        “rZxBGn1pzyM1“: {

            “cjY09NjFcgC4“: “1“,

            “cZRhwfBb6QhB“: “1“,

            “cJvSlN1pHORi“: “Custom BOM Part Number“,

            “cV6xruWVPiLD“: 1,

            “coRGk9Ny24jn“: “Assembly“,

            “cKECVNQxgTkH“: “”,

            “cGoUpxs9ZrSS“: “Outer Leg Assembly“,

            “cuMMrYE9PaiT“: “”,

            “c3VXFLgiBliK“: “”,

            “c1512506563215“: “10“,

            “c1512506622204“: 10

        },

}

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.”}

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

HEAD

URL_PARAM

X-OpenBOM-AppKey

X-OpenBOM-AccessToken

<catalogId>

string

string

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

<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.

Refer to Structures section.

Partial example response is:-

{

    “_id“: “338c9e50-fe66-4a17-8c9e-50fe66ea17b5“,

    “id“: “338c9e50-fe66-4a17-8c9e-50fe66ea17b5“,

    “sourceId“: “openbom“,

    “name“: “user S Items“,

    “nameuri“: “urn:openbom:name:user%40email:user%20s%20items“,

    “status“: “A“,

    “copyId“: null,

    “data“: {

        “rXEQzH8IAaUv“: {

            “cMyoRcZWWaBu“: “PN123“,

            “c840258267948564“: 23,

            “c927556586395610“: “noname“,

            “c926142038576119“: “In progress

       },

        …

}

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.”}

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

X-OpenBOM-AccessToken

<propertyTableId>

string

string

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

<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.

Refer to Structures section.

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”

    }

]

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.”}

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

X-OpenBOM-AccessToken

<bomId>

<json_params>

{

        “partNumberPropertyName“:””,

        “partNumber“:””,

        “propertyName“:””,

        “propertyValue“:””

}

string

string

string

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

<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.”}

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.”}

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

URL_PARAM

POST

X-OpenBOM-AppKey

X-OpenBOM-AccessToken

<catalogId>

<json_params>

{

        “partNumberPropertyName“:””,

        “partNumber“:””,

        “propertyName“:””,

        “propertyValue“:””

}

string

string

string

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

<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.”}

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.”}

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

}

  1. Bom document

TBD

  1. Catalog item in catalogs listing array

TBD

  1. Catalog document

TBD

  1. Property table item in property tables listing array

TBD

  1. 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

500

Internal Server Error

501

Not Implemented

503

Service Unavailable