Pagination

By default the API returns first 10 items of the collection. This can be changed with the limit argument.

To navigate through "pages" of the collection you can use the following pagination styles:

Offset-based

It's the default pagination style, which is supported by all resources.

The current position in the collection is controlled by the special offset argument. Like in arrays the offset starts at 0 (the default offset) and ends at the total count - 1.

Example:

Consider using the If-Match HTTP header to ensure, that the collection you browse was not changed. See also Caching.

Cursor-based

The cursor-based pagination helps to ensure, that new or removed items won't shift your position in the collection. However, not all resources support this pagination style.

Each item of a collection has an ID, which can be used to determine the position in the collection.

Here (assuming limit=10):

• before_id=15 will return ID#43 - ID#19 and is same as offset=0
• after_id=19 will return ID#15 - ID#5 and is same as offset=10

Also note, that if the collection gets new items:

The before_id=15 will still return ID#43 - ID#19.

Same if the item with ID#15 will be removed (before_id does not require the item with the ID to exist).

Resources, that support the cursor-based pagination, are ordered by ID, ascending or descending.

Also, unlike the offset-based pagination, for which we can just decrement or increment the offset value to retrieve previous and next pages accordingly, for the cursor-based pagination we can determine only the very previous and next pages, as they are relative to the current one (thus, for before_id we use the ID of the first item on the page and for after_id we use the ID of the last one).

Luckily, for some resources the API response includes links to the first and last page of the collection:

{
    "status": 200,
    "data": [ ... ],
    "resource": "test",
    "limit": 10,
    "total_count": 25,
    "first_url": "http://v5.kayako.com/api/v1/tests?before_id=11&count=25",
    "previous_url": "http://v5.kayako.com/api/v1/tests?before_id=11&count=25",
    "next_url": "http://v5.kayako.com/api/v1/tests?after_id=20&count=25",
    "last_url": "http://v5.kayako.com/api/v1/tests?after_id=20&count=25"
}

Date-based

The date-based pagination is useful when you want to "follow" the collection (e.g., to retrieve new items). However, not all resources support this pagination style.

Many resources have a timestamp field, that holds a distinct date of the resource. Such field can be used to determine the position of the resource in the collection.

Here (assuming limit=10):

• since=2015-08-28T20:34:59+05:00 will return ID#45 - ID#28 and is same as offset=0
• until=2015-08-30T16:58:07+05:00 will return ID#22 - ID#16 and is same as offset=10

Resources, that support the date-based pagination, are ordered by the date, ascending or descending.

Like arguments of the the cursor-based pagination since and until arguments do not require an item with the referenced date to exist.

Note, that taking the example above it's also easy to get new items of the collection just by using since=2015-08-31T12:45:30+05:00.

Like the cursor-based pagination the date-based one is also resistant to addition and/or removal of the collection's items.

Also, like for the cursor-based pagination we can determine only the very previous and next pages of the collection (we can use the date of the first item of the current page for since or until (depends on the order) and the date of the last item of the page for until or since).

To help here some resources include links to the first and last page of the collection into the response.