All Versions

Version 1
Version 2


Page tree

Supplier API v1

There is a newer version of this API!

Skip to end of metadata
Go to start of metadata

How to Use our API

The production URL for this API is:

https://supplier.cmix.com/api/v1

 

We also offer a sandbox or testing URL:

https://qa-supplier.cmix.com/api/v1

 

All requests must be made over HTTPS. All data is sent and received as JSON. When making requests, you receive the response data as JSON by properly setting the Accept header to application/json. Requests which contain a body must send the data as JSON by also setting the proper Content-Type header to application/json.

Authentication

All endpoints provided by this API require you to provide a valid credentials via HTTP Basic Authentication. Critical Mix will provide you with a username and password as a part of the on-boarding process for the use of this API. The username and password are used to create an authorization token, which must be included as an Authorization header with each request.

To create the authorization token, the username and password are concatenated to each other, separated by a colon. The resulting string is then Base64 encoded to create the token.

Example

Given the username criticalmix and the password topsecret, Base64Encode("criticalmix:topsecret") yields the authorization token Y3JpdGljYWxtaXg6dG9wc2VjcmV0.

The Authorization header would then be:

"Authorization": "Basic Y3JpdGljYWxtaXg6dG9wc2VjcmV0"

Authentication Errors

Requests which fail to properly authenticate will return on of the following HTTP Status Codes:

HTTP Status CodeMessageUsage
401: UnauthorizedUnauthorizedThe Authorization header is missing, is not of type Basic, or is improperly encoded
403: ForbiddenInvalid authentication credentialsAn invalid username or password was used to create the authorization token

 

Authentication errors will send the following additional headers with the response:

Header NameValueDescription

Content-Type

application/json

MIME type of the response body

 

The response body will contain a JSON string with the following data elements:

NameTypeDescription
messagestringUser friendly message describing the authentication error.

Example

{
    "message": "Invalid authentication credentials"
}

Requests

Requests to the various endpoints should use the appropriate specified verbs (HTTP Methods) as listed in the endpoint documentation.

If the request requires a body, the format of that body should always be well-formed JSON. The Content-Type header should be set to application\json when a JSON body is included with the request.

If an endpoint requires authentication, then the appropriate headers should be included, as detailed under Authentication.

Success Responses

HTTP Status Codes

Successful calls to the endpoints will return an appropriate HTTP Status Code from the following list: 

HTTP Status CodeUsage
201: CreatedA valid POST or PUT request resulted in the successful creation of a new resource.
200: OK

All successful calls

Success Response Headers

Header NameValueDescription
Content-Type
application/json

MIME type of the response body

Success Response Data

A response body will also be included in JSON format if one is specified for the endpoint. Check the documentation for each endpoint for details of what is included in each response.

Success Response Examples

Check the documentation for each endpoint for examples of the success response.

Error Responses

HTTP Status Codes

Calls to the endpoints which result in an error, or which are not able to successfully create or update the specified resource will return an appropriate HTTP Status Code from the following list: 

HTTP Status CodeUsage

400: Bad Request

The expected JSON body is missing or invalid, or the request is missing required parameters
404: Not FoundA non-existent resource has been requested, or data in the request body specifies a missing or invalid object.
500: Internal Server ErrorAuthentication error or any other error not covered by a different status code

Error Response Headers

Header NameValueDescription
Content-Type
application/json
MIME type of the response body

Error Response Data

NameTypeDescription
messagestringUser friendly error message
codenumberNumeric error code which can be used by Critical Mix to help troubleshoot any errors

Error Response Examples

{
    "message": "No properties received for update",
    "code": 5
}

 

Write a comment…