Limit-offset pagination method

Overview

This method is similar to the page number parameter approach. However, instead of appending a page number to the request URL, an offset parameter is used to indicate how many results have been returned so far (i.e. the start point for required data).

This method is rather like a database search: give me 5 records starting from the 15th record.

Limit-offset options

Option	Summary
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.
Offset parameter path	Enter the dot notation path for the data element in your response which contains the required offset - i.e. how many items should be skipped before the next page starts. Commonly (though not necessarily), this would be a path to a page field.
Limit	Enter the number of items to be returned per page. For example: 10.
Count parameter path	If required, enter the dot notation path for the data element in your response which contains the current count of records that have come back from the system. Commonly (though not necessarily), this would be a path to a count field. This value is not required for some APIs, therefore it's an optional field.
Total parameter path	Enter the dot notation path for the data element in your response which contains the total number of records that will be returned in this response, so we know when to stop paginating. Commonly (though not necessarily), this would be a path to a total field. This value is not required for some APIs, therefore it's an optional field.

Example

Suppose we set the following options:

Option	Value
Limit parameter path	limit
Offset parameter path	offset
Limit	5
Count parameter path	meta.count
Total parameter path	meta.total

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

GET https://my.shop/api/customers??limit=5&offset=0

The response will include the first page of data (sometimes with metadata regarding pagination). For example:

{
  "data": [
    {"name": "Gordon"},
    {"name": "Izzy"},
    {"name": "Mike"},
    {"name": "Ralph"},
    {"name": "Rex"}
  ],
  "meta": {
    "total": 50,
    "count": 5,
    "limit": 5,
    "offset": 5
  }
}

Requests for subsequent pages would increment the offset value by the limit value - for example:

GET https://my.shop/api/customers??limit=5&offset=5

...and then:

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

...and so on until 50 items (i.e. the total parameter path value) are returned.

When does pagination stop?

Pagination continues until the last page, when there is no more data to return.

Special notes

The limit offset pagination method is implemented using a Patchworks pagination variable which contains the next page offset:

<PageNo>[[pagination.offset]]</PageNo>

This note is for reference only - there should never be a need to access/change this variable.