Migration Guide

v2.0.0

This section provides instructions for transitioning from the Legacy API (v1) Download Endpoint to the new Platform API (v2) Download Endpoint for supplier compliance data. The new API version offers improved authorization and error handling, enhanced support and additional endpoints for interaction with a wider range of BOMcheck features.

Extended Platform API Features

The new API (v2) provides additional endpoints and functionality which were not available under the old API (v1). Therefor this guide provides migration details for the download endpoint only.

From v1 to v2 (Download)

Base URL (Host)

• In v1 the base URL for all API requests was www.bomcheck.net with a non-versioned URI /api/ preceding each available endpoint
• In v2 the base URL is provided at a dedicated API subdomain api.bomcheck.com with a versioned URI /v2/ preceding each available endpoint

Platform API (v2) Request
GET /v2/download HTTP/1.1
Host: api.bomcheck.com
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/zip

Legacy API (v1) Request
POST /api/download HTTP/1.1
Host: www.bomcheck.net
Content-Type: application/json
Accept: application/zip

Authorization Method

• In v1 authorization was conducted with an "apikey" which was set as a parameter directly on the POST request payload JSON object
• In v2 authorization is conducted with the use of a Bearer token which should be included as part of the Authorization header of each request
• Bearer tokens are available from your BOMcheck account manager

Platform API (v2) Request
GET /v2/download HTTP/1.1
Host: api.bomcheck.com
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/zip

Legacy API (v1) Request
POST /api/download HTTP/1.1
Host: www.bomcheck.net
Content-Type: application/json
Accept: application/zip

{
    "apikey": {apikey}, 
    // other params
}

Download via GET not POST

• In v1 the download endpoint was accessible via an HTTP POST request and the search criteria parameters were passed as in the POST payload JSON object
• In v2 the download endpoint is accessible via an HTTP GET request and the search criteria parameters should be passed in the URL query string

Platform API (v2) Request
GET /v2/download?format=1752B&supplier=987654321 HTTP/1.1
Host: api.bomcheck.com
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/zip

Legacy API (v1) Request
POST /api/download HTTP/1.1
Host: www.bomcheck.net
Content-Type: application/json
Accept: application/zip

Parameter Changes

• In v1 parameters were passed in the POST payload JSON object; in v2 parameters are passed in the URL query string (see GET not POST for more info)
• In v1 the apikey parameter was required; in v2 this authorization has been replaced with the Bearer token header (see Authorization Method for more info)
• In v1 the format parameter accepted "XML" (or "CSV"); in v2 the format parameter requires more detailed specification for XML files and accepts "1752A" or "1752B"
• In v1 the partNumbers parameter accepted a list of comma separated part numbers; in v2 the part numbers should be added to the query string partNumbers array using the partNumbers[]=123&partNumbers[]=456 convention
• In v1 the supplier AND partNumbers parameters could be omitted or left blank; in v2 EITHER the supplier OR partNumbers parameter is required with a valid value
• The v1 startdate parameter has been replaced in v2 with startDate (camel case convention), the date format remains YYYY-MM-DD (ISO8601)

Platform API (v2) Request
GET /v2/download?format=1752B&formatClass=C&supplier=987654321&partNumbers[]=123&partNumbers[]=456&startDate=2024-01-01 HTTP/1.1
Host: api.bomcheck.com
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/zip

Legacy API (v1) Request
POST /api/download HTTP/1.1
Host: www.bomcheck.net
Content-Type: application/json
Accept: application/zip

{
    "apikey": {apikey}, 
    "format": "XML", 
    "formatClass": "checkDthenC", 
    "supplier": "331736400", 
    "partNumbers": '"ABC123","DEF456","XYZ999"',
    "startdate": "2000-01-01"
}