Pagination

Requesting subsequent pages is based on a resource specific cursor - an attribute called version which can be found on all collection resources. Here's an example based on the brand resource:

{
  "id": "b1e2624f-f019-11e3-a0f5-b8ca3a64f8f4",
  "name": "Generic Brand",
  "deleted_at": null,
  "version": 791094
}

NOTE: The version attribute is simply a monotonically increasing integer. It is being incremented every time a resource is changed. This is a global parameter and it shouldn't be assumed that subsequent versions of the same resource will be incremented by 1.

First page

By default, the value of the after parameter will be assumed as equal 0 so it's not necessary to use it on the first page. For a request with no after parameter or after=0, the first page of products will be returned, even if a resource with version = 0 may not exist in the given collection. The body of the response will contain 2 JSON objects. The first one, data will be a collection of the requested resource type and the second one, version will contain the lowest and highest version number of resources included in the response.

{
    "data": [
        {
            "id": "0800273d-7d7f-11e5-e1c0-0aaccee64985",
            ...
        },
        ...
    ]
    "version": {
        "min": 11234566790,
        "max": 173456345676
    }
}

Subsequent pages

The response to that request should include a collection of 0 to n resources. The upper limit will probably be different depending on the endpoint. The highest version number x from this collection (the max attribute above) should be used to request the next page like:

/api/{version}/products?after=x

This should be repeated until an empty collection is returned. This will mean that all items of the collection have been returned.

Sorting

Objects in returned collections will be sorted by the version number in an ascending order.