OCAPI pagination 23.2

The Open Commerce API uses paging whenever it accesses a collection of resource instances. Paging enables the API to return data in chunks, instead of returning a complete collection all at once. Each chunk, depending on its position, links to the previous chunk and to the next chunk. You can explicitly configure paging by providing values for the start and count parameters:

  • start: Specifies the start location of the chunk within the collection of resource elements. Valid values range from 0 to 999; the default value is 0. The start location is not a page number; it is the position of the start element within the entire collection.
  • count: Specifies the number of resource instances to return in each chunk. Valid values range from 0 to 200; the default value is 25.

In the following example, a product search yields a collection of 99 total resource instances (shoes). The start property specifies that the requested chunk should start at position 10, and the count element specifies that the chunk should contain at most 5 resource instances. In the response, you can see the presence of the next and previous links; these links enable your application to navigate through the entire collection one chunk at a time.


REQUEST:
GET /dw/shop/v23_2/product_search?q=shoes&start=10&count=5 HTTP/1.1
Host: example.com
Accept: application/json

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 351
Content-Type: application/json; charset=UTF-8

{
  "_v" : "23.2",
  "query":"shoes",
  "total":99,
  "start":10,
  "count":5,
  "next":"http://example.com/dw/shop/v23_2/product_search?q=shoes&start=15&count=5",
  "previous":"http://example.com/dw/shop/v23_2/product_search?q=shoes&start=5&count=5",
  "hits":[{
    "product_id":123",
    "link":"http://example.com/dw/shop/v23_2/product/123",
    "name":"My Ultimate Shoe",
    ...
    },
    ...
  ]}
X OCAPI versions 15.x and 16.x will be retired on March 31, 2021. For dates and more information, see the OCAPI versioning and deprecation policy and this Knowledge Article.