#Overview

All the essential things you need to know.

#Root of the REST API

The REST API offers a set of endpoints that can be reached via the following root URI.

https://demo.akeneo.com/api/rest/v1
    

https://demo.akeneo.com is the host of the PIM you are trying to request via the REST API.

v1 means that you want to use the first (and only) version of the REST API. All URIs have to explicitly request this version. If you try to request another version of the REST API, you will receive a beautiful 404 error since there is only one version of the REST API for now.

#Available HTTP Verbs

In the first version of the REST API, we use 4 HTTP verbs. They are the following.

#Data format

JSON is the only format supported by the REST API for now.

This means that data extracted thanks to the REST API will be in JSON format. And if you need to create or update data using the REST API, you will also need to use the JSON format.

For each entity, we have defined a standard format that is completely detailed in the Concepts & resources section.

#Format headers

When creating and updating data via the REST API, you will need to explicitly tell the REST API that you are providing JSON content by using a Content-type header set to application/json.

#Example

curl -X PATCH /api/rest/v1/categories/mycategory \
      -H "Content-type: application/json" \
      -d '{
            "labels": {
              "en_US": "My amazing category"
            }
        }'
    

HTTP/1.1 415 Unsupported media type
    
    {
      "code": 415,
      "message":"The ‘Content-type’ header is missing. ‘application/json’ has to specified as value."
    }
    

HTTP/1.1 415 Unsupported Media Type
    
    {
      "code": 415,
      "message": "‘xxx’ in ‘Content-type’ header is not valid.  Only ‘application/json’ is allowed."
    }
    

When getting data from the PIM through the REST API, you can use an Accept header set to application/json to specify that you expect the REST API to return data in JSON format.

#Example

curl /api/rest/v1
      -H "Accept: application/json"
    

HTTP/1.1 406 Not Acceptable
    
    {
      "code": 406,
      "message": "‘xxx’ in ‘Accept‘ header is not valid. Only ‘application/json‘ is allowed."
    }
    

#Scope of the REST API

For each new PIM versions, we add more and more resources to our REST API scope.
For a detailed presentation as well as the format of each of these resources, take a look to the Concepts & resources documentation.

Also, you will find the complete reference of the endpoints available for each of these resources in the REST API Reference. You can also get the list of these endpoints by request, see List of available endpoints.

#List of available endpoints

By requesting the root URI of the REST API, you get the list of all available endpoints.

#Example

Request

curl /api/rest/v1
      -H "Accept: application/json"
    

Response

HTTP/1.1 200 OK
    
    {
      "host": "http://demo.akeneo.com",
      "authentication": {
        "fos_oauth_server_token": {
          "route": "/api/oauth/v1/token",
          "methods": ["POST"]
        }
      },
      "routes": {
        "pim_api_family_list": {
          "route": "/api/rest/v1/families",
          "methods": ["GET"]
        },
        "pim_api_family_get": {
          "route": "/api/rest/v1/families/{code}",
          "methods": ["GET"]
        },
        "pim_api_family_create": {
          "route": "/api/rest/v1/families",
          "methods": ["POST"]
        },
        "pim_api_family_partial_update": {
          "route": "/api/rest/v1/families/{code}",
          "methods": ["PATCH"]
        }, 
        "pim_api_product_delete": {
          "route": "/api/rest/v1/products-uuid/{uuid}",
          "methods": ["DELETE"]
        }
      }
    }
    

#Fair-usage protection

Our API facilitates the integration of Akeneo PIM with external systems. To maintain optimal user experience and platform stability, our platform employs various protection mechanisms to prevent over-usage. Please adhere to the following usage guidelines:

#Maximum Concurrent API Calls

• Per PIM Connection: Up to 4 concurrent API calls are allowed for each individual PIM connection.
• Per PIM Instance: Up to 10 concurrent API calls are allowed across the entire PIM instance.

#Rate Limits Within a Specific Amount of Time

• General API Requests: up to 100 API requests per second per PIM instance.
• updating & creating attribute options: up to 3 API requests per second per PIM instance.

#Handling Over-Usage

If your API usage exceeds these limits, the platform’s protection mechanisms may be triggered, resulting in blocked requests and HTTP status code 429 responses. As a REST API consumer, you have to keep in mind that your integration with Akeneo PIM should anticipate this throttling and should be able to handle failures.

Bursts are allowed, but continuous over-usage will trigger the protection sooner.

To effectively manage and mitigate over-usage, we recommend implementing the following strategies:

Check for "Retry-After"

If the HTTP 429 response includes a "Retry-After" header, wait the specified number of seconds before retrying.

Implement Exponential Backoff

Use increasing delays between retry attempts (e.g., 10s, 30s, 60s) to reduce the load on the API.

Use Batch Endpoints

Combine multiple requests into a single API call using batch endpoints to minimize the number of calls.

Implement a Cache Layer

Cache frequently accessed data on the client side to reduce repetitive API requests and improve response times.

#Introducing the REST API reference

You want to dig deeper and know every inch of the REST API?

We have crafted a complete reference of our REST API. So feel free to browse it.

There, you will find for each available endpoint, a description of what it does, what are the expected parameters in the request and what are the different responses you will be able to get, being successes or errors.