Upload
others
View
3
Download
0
Embed Size (px)
Citation preview
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.
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-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.
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 X-OpenBOM-AppKey string
HEAD
URL_PARAM
X-OpenBOM-AccessToken
<catalogId>
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."}
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
X-OpenBOM-AppKey
X-OpenBOM-AccessToken
string
string
HEAD
URL_PARAM
POST
Content-Type
<catalogId>
<json_params>
{
"partNumberPropertyName":"", "partNumber":"", "propertyName":"", "propertyValue":""
}
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."}
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
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."}
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