Next page token pagination method

Overview

This method is a slight variation on the next page URL approach. Instead of receiving a full URL in the response, it contains a 'token' (usually a random string/hash). The receiving system uses this token to keep track of the position of the last record in the current page of data.

Next page token options

Option	Summary
Token parameter name	Enter the name of the URL parameter which holds the token for requesting the next page.
Limit parameter path	Enter the dot notation path for the data element in your response which contains the maximum number of items that the API should return in a single page of a paginated response. Commonly (though not necessarily), this would be a path to a limit field.
Limit	Enter the number of items to be returned per page. For example: 10.
Path to token in payload	Enter the dot notation path of the next page token within the payload.

Example

Suppose we set the following options:

Option	Value
Token parameter name	page_token
Limit parameter path	limit
Limit	10
Path to token in payload	links.next

...and we send a request to get the first page of data:

GET https://my.shop/api/customers?limit=10

The response will include the first page of data, together with a next page token that should be used to get the next page of results. For example:

{
  "data": [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"},
    {"id": 3, "name": "Charlie"},
    {"id": 4, "name": "Lyn"},
    {"id": 5, "name": "John"},
    {"id": 6, "name": "Gordon"},
    {"id": 7, "name": "Izzy"},
    {"id": 8, "name": "Mike"},
    {"id": 9, "name": "Ralph"},
    {"id": 10, "name": "Rex"}
  ],
  "links": {
    "next": "abcd5780HJKLMN0PqR24"
  }
}

Notice the links.next section at the end of this response, which includes our next page URL. So, our request for the next page of results would be:

GET https://my.shop/api/customers?limit=10&page_token=abcd5780HJKLMN0PqR24

When does pagination stop?

Pagination continues until the token is no longer included in the payload.