Versioning

VERSIONING

API_MINIMUM_VERSION = 3
API_CURRENT_VERSION = 12
source

In order to avoid breaking changes, the INVENTORUM API is versioned and a specific API version should be given with any request in the HTTP header X-Api-Version:

X-Api-Version: 12

Bugfixes and minor feature additions might be made without advancing the version number. This may include additional request parameters or response fields. Any breaking changes will be made by advancing the version number.

This documentation will contain examples with specific API versions.

Paging

Most list endpoints (e.g. GET /api/products/) are paged. The paging can thereby be controlled with the two optional query parameters limit and page:

Request

curl -X GET \
  'https://app.inventorum.com/api/products/?limit=5&page=1' \
  -H 'Authorization: Bearer {{oauth_token}}' \

• page parameter always defaults to the first page.
• limit default is 40 items per page, but may vary by endpoint.

Response
The response for paged list endpoints is always structured as follows:

{
    "total": 142,
    "data": [...]
}

The total thereby denotes the overall number of items and can be used to derive the total number of pages.

Rate limiting

If the INVENTORUM API receives too many requests from one client or access token in a short period of time, it might respond with the HTTP error status 429 Too Many Requests.

Rate limit: 20 requests/sec

This is a security measure against potentially harmful requests. In such a case, the request should be retried after some time.

Error handling

Following REST best practices, the INVENTORUM API leverages HTTP status codes to indicate errors. 4xx codes are thereby returned in response to client errors (e.g. 400 Bad Request ) and 5xx error codes ( e.g. 500 Internal Server Error)to indicate server errors . If the API responds with 2xx status codes, the request was handled correctly or accepted in case of asynchronous operations (202 Accepted).

In addition to an HTTP error code, the API generally also returns a JSON body in the response with additional information, for example:

{
    "detail": "Validation error",
    "error": {
        "description': "Validation error",
        "fields": {
            "quantity":[ "Ensure this value is greater than or equal to 0."],
        },
        "key":"common.validation_error"
    }
}

Headers

Required headers:

Accept: application/json
Authorization: Bearer {{oauth_token}}
X-Api-Version: {{api_version_number}}

Any additional headers will be described by request.