[What is a REST API?](#what-is-a-rest-api)
[How does Quable's REST API work?](#how-does-quables-rest-api-work)
[Data format](#data-format)
[API versions](#api-versions)
-- [API V4](#api-v4)
-- [API V5](#api-v5)
[API specification](#api-specifications)
[API limitation](#api-limitation)

---

## What is a REST API?

APIs are interfaces that allow other applications to interact with and access a system’s features, functionalities, and data in a systematic manner. 

Quable’s API is organized on [REST](https://en.wikipedia.org/wiki/REST) (Representational State Transfer) principles. REST is an architectural style that describes how distributed software systems can expose consistent interfaces to their resources. 

A REST API is a type of API that uses HTTP requests to interact with resources. 
Resources can be anything from database records to product images. REST APIs are typically stateless, meaning that each request is independent of the previous one. This makes them very scalable and easy to use.

Quable’s REST API endpoints are resource-centric and use HTTP protocol to access and act upon them.

---

### How does Quable's REST API work?

Quable's REST API is organized around a set of resources, such as documents, classifications, variants, links, assets...
To access a resource, you send an HTTP request to the appropriate endpoint. 
For example, to get a list of all documents, you would send a GET request to the `/documents` endpoint.

Quable's REST API supports the following HTTP methods:

* **GET:** Retrieve a resource.
* **POST:** Create a new resource.
* **PUT:** Update an existing resource.
* **DELETE:** Delete a resource.

---

### Data Format

REST APIs support:
* [JSON format](https://www.json.org/json-en.html). 
* [HAL+JSON format](https://guide-api-rest.marmicode.fr/autres-specifications/h.a.l.)
* [JSON-LD format](https://json-ld.org)

All data created, updated, or retrieved via the Quable PIM API must respect those formats, encoded with UTF-8. 
We recommend to use HAL+JSON or JSON-LD

---

### API Versions

In our ongoing efforts to provide the most reliable and stable environment, Quable PIM currently has two API versions:

#### API v5

This is Quable PIM's newest & most performant API version.

#### API v4
This is old Quable PIM API.
There are no plans to deprecate this version, however endpoint deprecations are periodically scheduled.

!!!warning **Do not use this API while developing new script.**
If you're updating scripts or feeds, don't hesitate to take a look at version 5, which is simpler, multilingual and high-performance.
!!!

!!!warning **Deprecations**
Please have a look at the list of [endpoints deprecation](/quable-api/deprecation) for regular updates.
!!!

---

### API Specifications

|   Specification        | API v5                            | <span style="color:grey">API v4</span>                           |
| -----------------------| --------------------------------- | ---------------------------------                                |
| Endpoint - Domain      | `https://{{instance}}.quable.com` |<span style="color:grey">https://{{instance}}.quable.com</span>   |
| Endpoint - Prefix      | `/api/`                           |<span style="color:grey">/api_1.php/</span>                       |
| Endpoint Deprecations  | [API v5 Endpoint Deprecations](/quable-api/deprecation)    |<span style="color:grey">API v4 Endpoint Deprecations</span>      |
| Data format            | JSON, JSON+LD, HAL+JSON           |<span style="color:grey">JSON</span>                              |
| Token                  | Bearer                            |<span style="color:grey">Bearer</span>                            |
| Protocol               | HTTPs                             |<span style="color:grey">HTTPs</span>                             |
| Multilingual           | Yes                               |<span style="color:grey">No</span>                                |

---

## API limitation

!!!warning
Depending on the volume of API calls, you may receive responses with the HTTP response code **429**. 
In this case, your applications must reduce the number of calls or wait a few seconds before resuming calls.
!!!

Restrictions : 
- _6K calls per 10 minutes bucket_ : If exceeded, 429 HTTP response code will be returned (10 minute bucket)  
- _300K calls per day_ : If exceeded, 429 HTTP response code will be returned (1 day bucket)