OpenBOM API Specification Document


Index

Overview

Methods

1. Login

2. List BOMs

3. List Top Level BOMs

4. List Order BOMs

5. List Catalogs

6. List Property tables

7. Get specific bom document

8. Get specific catalog document

9. Get specific property table document

10. Update bom document property value

11. Update catalog document property value

12. Find BOM documents by parameters

13. List Templates

14. Create BOM document

15. Add new row to the bom document

16. Get Image File

17. Upload Image File to BOM

18. Upload Image File to Catalog

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 OpenBOM 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 support@openbom.com[a]

  1. In addition, access token must be provided in every request, except for the  /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. 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.

  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 requests per second is the top limit (Subject to changes in the future[b]). 429 response status code will be returned when limit is reached.

Methods

1. Login

Authenticate the user with the system and obtain the access token[c]. 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":"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 Top Level BOMs

Get all only top level boms accessible by the user

Request

Method

URL            

GET

/toplevelboms

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

  -H 'x-openbom-accesstoken: eyJraWQiOiJjSVAyRU1NYUZuSnFhSkhUaD...' \

  -H 'x-openbom-appkey: developerappkey'

Response

Status

Response

200

Response will be an object containing the list of top level 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."}

4. 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": "",

        "numUnits": 0,

        "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",

                "numUnits": 3,

        "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",

                "numUnits": 1,

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

5. 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."}

6. 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."}

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

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

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

10. 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."}

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

HEAD

URL_PARAM

POST

X-OpenBOM-AppKey

X-OpenBOM-AccessToken

Content-Type

<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

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

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

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

X-OpenBOM-AccessToken

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

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
           ]
       ]
   }
]

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

13. List Templates

Get all templates accessible by the user

Request

Method

URL            

GET

/templates

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

  -H 'x-openbom-accesstoken: eyJraWQiOiJjSVAyRU1NYUZuSnFhSkhUaD...' \

  -H 'x-openbom-appkey: developerappkey'

Response

Status

Response

200

Response will be an object containing the list of template documents properties (array) . Each item in the templates listing array has the following structure.

  {

    "templateId": "",

    "id": "",

    "name": "",

    "nameuri": "",

    "user": "",

    "status": "",

    "createdBy": "",

    "created": 0,

    "createdString": "",

    "modified": 0,

    "modifiedString": ""

  }

An example response is:-

[

  {

    "templateId": "cc12e1fc-140e-4a6b-92e1-fc140efa6b0f",

    "id": "cc12e1fc-140e-4a6b-92e1-fc140efa6b0f",

    "name": "test template",

    "nameuri": null,

    "user": null,

    "status": "A",

    "createdBy": "user@email",

    "created": 1573740501855,

    "createdString": "2019-11-14T14:08:21.855Z",

    "modified": 1573740501855,

    "modifiedString": "2019-11-14T14:08:21.855Z"

  },

  {

    "templateId": "17e1858d-8656-4134-a185-8d86566134f2",

    "id": "17e1858d-8656-4134-a185-8d86566134f2",

    "name": "TemplateFormulaTemplate",

    "nameuri": null,

    "user": null,

    "status": "A",

    "createdBy": "user@email",

    "created": 1587617206269,

    "createdString": "2020-04-23T04:46:46.269Z",

    "modified": 1587617206273,

    "modifiedString": "2020-04-23T04:46:46.273Z"

  }

]

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

14. Create bom document

Creates bom document.

Request

Method

URL            

POST

/bom/create

Type

Params

Values

HEAD

HEAD

POST

X-OpenBOM-AppKey

X-OpenBOM-AccessToken

<json_params>

{

        "docName":"",

[optional]        "bomPartNumber":"",

[optional]        "catalogId":"",

[optional]        "templateId":""

}

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

<json_params>

{

        "docName":"new bom", //Unique Name of the new BOM document,

must be unique

[optional] "bomPartNumber":"partnumber", //Part number to be set to the bom

[optional] "catalogId":"", //Catalog that will be assigned to the bom

[optional] "templateId":"" //Templated will be used to create the bom

}

Example

curl -X POST \

http://developer-api.openbom.com/bom/create \

  -H 'x-openbom-accesstoken: eyJraWQiOiJjSVAyRU...' \

  -H 'x-openbom-appkey: developerappkey' \

  -H 'content-type: application/json' \

  -d '{

        "docName":"new bom",

        "bomPartNumber":"PN1",

        "catalogId":"",

        "templateId":""

}'

Response

Status

Response

200

Response will be a json object representing bom document.

Refer to Structures section.

400

{"error": "BOM exists with name, BOM names are unique."}

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

15. Add new row to the bom document

Adds a new row to specified bom document. Formulas will be applied to the new row if the bom document was created using template and template has formulas defined.

Request

Method

URL            

PUT

/bom/<bomId>/parts

Type

Params

Values

HEAD

HEAD

URL_PARAM

POST

X-OpenBOM-AppKey

X-OpenBOM-AccessToken

<bomId>

<json_params> //Array of objects

[

  {

    "partNumber":"1",

    "properties": {

        "column1":"",

        "column2":"",

        "column3":""

    }

  },

  {

    "partNumber":"2",

    "properties": {

        "column1":"",

        "column2":"",

        "column3":""

    }

  }

]

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 add a new row to. Can be taken from listing response.

<json_params> Array of json objects:

[

  {

    "partNumber":"1", //The partnumber property value for a new row

    "properties": {   //Names and values for the properties of the new row

        "Column1":"",   // Must match column names in the bom document.

        "column2":"",

        "column3":""

    }

  }

]

Example

curl -X PUT \

http://developer-api.openbom.com/bom/49c6f1f3-7006-48fc-86f1-f3700628fcff/parts \

  -H 'x-openbom-accesstoken: eyJraWQiOiJjSVAyRU...' \

  -H 'x-openbom-appkey: developerappkey'' \

  -H 'content-type: application/json' \

  -d '[

          {

                "partNumber":"1",

                "properties": {  

              "column1":"",  

              "column2":"",

              "column3":""

               }

           },

          {

             "partNumber":"1",

             "properties": {  

           "column1":"",  

           "column2":"",

           "column3":""

             }

         }

]'

Response

Status

Response

200

[{"partNumber":"OK"|"partNumber":"ERROR"}

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

16. Get image file

Retrieve image file by url from openbom document. The url is provided inside the bom or catalog json response from get specific bom or catalog APIs.

Request

Method

URL            

GET

https://developer-api.openbom.com/document/<documentId>/image?filename=<filename>

Type

Params

Values

HEAD

HEAD

URL_PARAM

URL_PARAM

X-OpenBOM-AppKey

X-OpenBOM-AccessToken

<documentId>

<filename>

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

Example

curl -X GET \

https://developer-api.openbom.com/document/ec539312-72bf-4ab1-9393-1272bf7ab120/image?filename=openbom.png \

  -H 'x-openbom-accesstoken: eyJraWQiOiJjSVAyRU...' \

  -H 'x-openbom-appkey: developerappkey'

Response

Status

Response

200

Response will be an image file.

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

17. Upload image file for boms

Update specific cell in bom document with image file.  

Request

Method

URL            

POST

https://developer-api.openbom.com/document/<documentId>/image

Type

Params

Values

HEAD

HEAD

URL_PARAM

POST

X-OpenBOM-AppKey

X-OpenBOM-AccessToken

<documentId>

"file"

"partNumber"

"imageProperty"

string

string

string

binary

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 --location --request POST 'https://developer-api.openbom.com/document/277c6246-005d-449a-bc62-46005dd49ad0/image' \

--header 'X-Openbom-AccessToken: eyJraWQiOiJrZHJI...' \

--header 'X-Openbom-AppKey: developerappkey' \

--form 'file=@/Users/user/Downloads/image.jpg' \

--form 'partNumber=part1' \

--form 'imageProperty=Thumbnail image'

Response

Status

Response

201

Created

400

BAD_REQUEST

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

18. Upload image file for catalog

Update specific cell in catalog document with image file.  

Request

Method

URL            

POST

https://developer-api.openbom.com/catalog/<documentId>/image

Type

Params

Values

HEAD

HEAD

URL_PARAM

POST

X-OpenBOM-AppKey

X-OpenBOM-AccessToken

<documentId>

"file"

"partNumber"

"imageProperty"

string

string

string

binary

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 --location --request POST 'https://developer-api.openbom.com/catalog/277c6246-005d-449a-bc62-46005dd49ad1/image' \

--header 'X-Openbom-AccessToken: eyJraWQiOiJrZHJI...' \

--header 'X-Openbom-AppKey: developerappkey' \

--form 'file=@/Users/user/Downloads/image.jpg' \

--form 'partNumber=part1' \

--form 'imageProperty=Thumbnail image'

Response

Status

Response

201

Created

400

BAD_REQUEST

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 documen[d]t[e]

        {

        "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",

            "Quantity",

            "Cost"

        ],

        "cells": [ // Array of arrays representing tabular data, order is according to columns array

            [

      "part2",

   "https://developer-api.openbom.com/document/02ac0179-ffe5-423b-ac01-79ffe5123bbf/image?filename=Screw.png",

      "part2 description",

      3,

      5

    ],

    [

      "part1",

      "null",

      "part1 description",

      1,

      2

    ]

        ],

        "totalCells": [ // Array of total values for each column

            [

                "",

                "",

                "",

                "",

                7

            ]

        ]

    }

  1. Catalog item in catalogs listing array

    {

        "nodeId": 0,

        "itemsId": "0",

        "id": "0",

        "name": "",

        "user": "",

        "status": "",

        "permissionString": "",

        "permission": 0,

        "modifiedBy": "",

        "modified": 0

    }

  1. Catalog document

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

  1. Property table item in property tables listing array

TBD

  1. Property table document

Glossary

Conventions

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

[a]We should consider in a future release, using Okta to manage API keys which are essentially tokens - https://support.okta.com/help/Documentation/Knowledge_Article/API-Access-Management-1843045799

[b]Can you clarify this ? 5 concurrent requests over how many seconds ?

[c]You should explain more clearly that this must be done first before any requests can be made.

[d]It would be better if the dates were returned in ISO8601 format ? We are returning this format now:  "22 Jun 2018; 24:41:29 GMT"

[e]Can you provide a populated example and explain the structure ?