Custom relative URI pagination method

Overview

Each page is denoted by the ID of the last object it holds, rather than its page. For example, if a 'page' returns 10 customers, then the ID of the last customer will be passed in the URL to get the next page.

Custom relative URI options

Option	Summary
Link 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.
Last ID parameter name	Enter the name of the query parameter to be passed into the URL to tell the receiving system the last record we received (so the receiving system knows where to start for the next page of data to return). A commonly used name is: last_id .
Limit	Enter the number of items to be returned per page. For example: 10.
ID key	Enter the unique identifier key for each item in your data. For example, if the endpoint is pulling a list of users, this might be: user_id.

Example

Suppose we set the following options:

Option	Value
Link parameter path	limit
Last ID parameter name	starting_after
Limit	10
ID key	id

The following URL will be generated to get the first page:

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

Notice our link parameter path (limit) and the actual limit value (10) at the end of the request. Our first page would look something like the example below:

{
  "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"}
  ],
}

When pagination runs, it will look for the last id key in the payload, and use that as the starting point for the next request. So the request for page 2 will be:

GET http://my.shop/api/customers?limit=10&starting_after=10

Notice our link parameter path (limit) and the actual limit value (10) at the end of the request, followed by our Last ID parameter name (starting_after) set to the last id in the response.

A sample response for this request is below:

{
  "data": [
    {"id": 11, "name": "Josh"},
    {"id": 12, "name": "Adam"},
    {"id": 13, "name": "Tom"},
    {"id": 14, "name": "Aaron"},
    {"id": 15, "name": "Conor"},
    {"id": 16, "name": "Luke"},
    {"id": 17, "name": "Andrew"},
    {"id": 18, "name": "Nathan"},
    {"id": 19, "name": "Lee"},
    {"id": 20, "name": "Dean"}
  ]
}

When does pagination stop?

Pagination continues until the the number of items in the payload is less than the limit, or the page returns an error code.