# API specification

Commerce Layer Provisioning API is a fast [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer) API 100% compliant with the [JSON API](http://jsonapi.org/format/) specification (v1.0). It supports compound documents, sparse fieldsets, resource linking, filtering, sorting, pagination, and more. To learn more about how to leverage those features, the basic CRUD actions syntax and payloads you can refer to the [Core API documentation](https://app.gitbook.com/o/-Lfu_B3DKew-kvoEWzTk/s/-LgByaSP8eKjad-MIuHE/):

* [Fetching resources](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/fetching-resources)
* [Fetching relationships](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/fetching-relationships)
* [Including associations](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/including-associations)
* [Sparse fieldsets](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/sparse-fieldsets)
* [Sorting results](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/sorting-results)
* [Pagination](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/pagination)
* [Filtering data](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/filtering-data)
* [Creating resources](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/creating-resources)
* [Updating resources](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/updating-resources)
* [Deleting resources](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/deleting-resources)

{% hint style="warning" %}
All the strings passed to the API must be **UTF-8** encoded.
{% endhint %}

## Base endpoint

All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure) to the following base endpoint:

```http
https://provisioning.commercelayer.io
```

## Headers

Include the following HTTP request headers when making calls to the Provisioning API endpoints:

<table><thead><tr><th>Header</th><th data-type="checkbox">Required</th><th>Details</th></tr></thead><tbody><tr><td><strong><code>Accept</code></strong></td><td>true</td><td>Must be <code>application/vnd.api+json</code>.</td></tr><tr><td><strong><code>Accept-Version</code></strong></td><td>false</td><td>Must be <code>v1</code> (learn more about <a href="#api-versioning">versioning</a>).</td></tr><tr><td><strong><code>Content-Type</code></strong></td><td>true</td><td>Must be <code>application/vnd.api+json</code> (required only for <code>POST</code>, <code>PUT</code>, and <code>PATCH</code> requests).</td></tr><tr><td><strong><code>Authorization</code></strong></td><td>true</td><td>Must be <code>Bearer {{your_access_token}}</code>.</td></tr></tbody></table>

Where `{{your_access_token}}` is the access token you get by [authenticating](https://docs.commercelayer.io/provisioning/getting-started/authorization) to the Provisioning API.

## API versioning

The **Accept-Version** header is optional and will be used to manage future versioning. When different versions of the Provisioning API are available you'll be able to request a specific one just by changing it as follows:

```http
Accept-Version: v{{version}}
```

Where `{{version}}` is the unique progressive number that identifies the version you want to use.

{% hint style="info" %}
The latest version of the Provisioning API is **v1** — use `v1` as the **Accept-Version** header to make your calls.
{% endhint %}

## Rate limits

The requests you perform to the Provisioning API are currently subject to the [same rate limits](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/rate-limits#uncacheable) as the *uncacheable* requests to the Core API in *live* mode and differentiated by [limit type](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/rate-limits#other-endpoints).

<table><thead><tr><th width="100">Limit type</th><th width="200">Max number of requests</th><th>Time window</th></tr></thead><tbody><tr><td><em>Average</em></td><td><strong>200</strong> (to all endpoints)</td><td><strong>1 min</strong></td></tr><tr><td><em>Burst</em></td><td><strong>50</strong> (per endpoint)</td><td><strong>10 secs</strong></td></tr></tbody></table>

{% hint style="info" %}
The Core API `/oauth/token` endpoint you need to use for [authentication](https://docs.commercelayer.io/provisioning/authorization#getting-an-access-token) is subject to [stricter limits](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/rate-limits#authentication-endpoint) (**max 30 reqs / 1 min**).
{% endhint %}

IP addresses that exceed the rates above will be blocked until the frequency of the specific call drops below the allowed limit.

## Errors

Commerce Layer Provisioning API uses [HTTP response codes](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) to show the success or failure of an API request.

* Codes in the `2xx` range indicate success.
* Codes in the `4xx` range indicate an error that failed given the information provided (e.g. bad request, failed validation, or authentication issues).
* Codes in the `5xx` range indicate an unhandled error (these are rare and should never happen).

For a complete list of all the possible error codes, messages, and descriptions please refer to the [related section](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/handling-errors) of the Core API documentation.

{% hint style="warning" %}
Correct error handling is important. We recommend writing code that gracefully handles all possible API exceptions.
{% endhint %}