#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 is provided to connect Akeneo PIM to external systems.

Our recommendations on maximum usage are:

• a maximum of 4 concurrent API calls per PIM Connection
• a maximum of 10 concurrent API calls in total on a PIM instance

Our PIM Cloud service has currently no rate limit based on API requests per unit of time or per IP, except for the API dedicated to updating & creating attribute options.

However, our platform is protected through a number of preservation mechanisms to avoid impacting the user experience and platform stability in case of over-usage.

When these protection mechanisms are triggered, we will return an HTTP status code 429 with a Retry-After header. The "Retry-After" property indicates how many seconds you have to wait before your next API request.

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.

This API protection is typically triggered above 100 API requests per second per PIM instance, but it depends as well on the duration of the over-usage.

That is to say, bursts are allowed, but continuous over-usage will trigger the protection sooner.

#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.