#Pagination

The vast majority of the responses containing a collection of resources will be paginated. Take a look at our reference to find out which one.

#The limit parameter

On certain endpoints, you'll be able to use the parameter limit. When available for the endpoint, by default, we will return pages of 10 entities. You can tuned this number by using the limit parameter as shown in the example below.

#Example

curl -X GET /api/rest/v1/categories?limit=25
    

This will set the number of entities by page to 25 instead of 10.

HTTP/1.1 422 Unprocessable entity
    
    { 
      "code":422, 
      "message":"You cannot request more than 100 items." 
    }
    

#The Search-after method

We provide another pagination method, the 'Search-after' method, for high-volume entities, such as products, product models, published products, assets, reference entities, and reference entity records.

We strongly recommend using this method if you want to have good performances instead of the Offset method.

Please note that when you use this method, entities are sorted by product primary key, and the with_count parameter is unavailable to speed up performance. Also, a search_after query parameter is used as a cursor.

#Example

#Request

curl -X GET /api/rest/v1/products-uuid?pagination_type=search_after&search_after=qaXbcde&limit=20
    

This request returns the 20 products situated after the qaXbcde cursor.

#Response

The response will respect this structure, even if there are no items to return.

HTTP/1.1 200 OK
    
    {
      "_links": {
        "self": {
          "href": "https://demo.akeneo.com/api/rest/v1/products-uuid?pagination_type=search_after&search_after=qaXbcde&limit=20"
        },
        "first": {
          "href": "https://demo.akeneo.com/api/rest/v1/products-uuid?pagination_type=search_after&limit=20"
        },
        "next": {
          "href": "https://demo.akeneo.com/api/rest/v1/products-uuid?pagination_type=search_after&search_after=qaXbcdedsfeF&limit=20"
        }
      },
      "_embedded": {
        "items": [
          ...
        ]
      }
    }
    

#The Offset method

This is the default pagination type. It's available for all the resources, except the reference entity and the reference entity record: only the search-after method is available for these two resources.

The Offset method is the most common way to paginate resources (with an offset on query), but it's less efficient than the Search-after method.

When you want to use the classical method on products, product models, published products or assets, you can set the pagination_type query parameter to page but this is not mandatory since this is the default pagination.

The page query parameter indicates the page number, the page being the one requested. By default, this query parameter is equal to 1.

#Example

#Request

curl -X GET /api/rest/v1/categories?pagination_type=page&page=2&limit=20
    

This will return the second page of entities, the entities being paginated by 20.

#Response

The response will have this structure, even if there are no items to return.

HTTP/1.1 200 OK
    
    {
      "_links": {
        "self": {
          "href": "https://demo.akeneo.com/api/rest/v1/categories?page=2&limit=20"
        },
        "first": {
          "href": "https://demo.akeneo.com/api/rest/v1/categories?page=1&limit=20"
        },
        "previous": {
          "href": "https://demo.akeneo.com/api/rest/v1/categories?page=1&limit=20"
        },
        "next": {
          "href": "https://demo.akeneo.com/api/rest/v1/categories?page=3&limit=20"
        }
      },
      "current_page": 2,
      "_embedded": {
        "items": [
          ...
        ]
      }
    }
    

// This request
    curl -X GET /api/rest/v1/products-uuid?pagination_type=page
    
    // is equal to this request
    curl -X GET /api/rest/v1/products-uuid
    

#Limitation

When trying to request a quite high page number, you will notice that this method spend more and more time to respond. This method can also be responsible for giving you duplicates. That is why we introduced another way to request paginated resources, see the Search-after method. It is only avalailable on products, product models, published products, assets, reference entities and reference entity records right now.

For somes high volume entities, an offset limit exist, after that an error with code 422 will be sent back.

    // Max offset for product trying to fetch after the 10.000th product
    curl -X GET api/rest/v1/products-uuid?page=101&limit=100
    {
        "code": 422,
        "message": "You have reached the maximum number of pages you can retrieve with the \"page\" pagination type. Please use the search after pagination type instead",
        "_links": {
            "documentation": {
                "href": "http://api.akeneo.com/documentation/pagination.html#the-search-after-method"
            }
        }
    }