Endpoints which return a list of objects follow a common pagination pattern.

Common Standard: Page Based

The common pagination our endpoints follow is page-based. The maximum number of elements per page is usually 30.

Request

When making a GET request, you can specify the following query parameters to control the response:

  • page - the page number you want to begin the search from;
  • pageSize - the maximum number of objects to be returned from the query (should be 30 or less).

For example, the following request would return 30 results, skipping the first 30 on page 1:

GET /settlements?page=2&pageSize=30

Response

In the response there is a meta object which contains the following details:

  • page - the page number you want to begin the search from
  • pageSize - the maximum number of objects to be returned from the query
  • total - the total number of objects

The structure of the meta object is:

"meta": {
    "pagination": {
      "page": 2,
      "pageSize": 30,
      "total": 250
    }

You should attempt to retrieve the calculated number of pages BUT stop retrieving new pages when the results array is empty.