Pagination

Overview

List methods that return a collection of resources are paginated using next or offset and limit query parameters.

๐Ÿ“˜

Default Values

The default limit value is 10 and default offset value is 0.

๐Ÿ“˜

Descending Order

Resources are returned in reverse order by id by default, meaning the API returns the last 10 resources in a collection.

Why use descending order? It makes it easier to retrieve the most recent records, for example to get 5 most recently created people use:

GET /v1/people?limit=5

To obtain the next page of 10 resources use the next query parameter value (recommended) or specify offset=10 query parameter, then offset=20 and so on.

You can increase the number of resources returned at a time using the limit parameter.

๐Ÿ“˜

Maximum Limit

The maximum value for the limit parameter is 100.

๐Ÿ“˜

Deep Pagination Support

If you are going deep into result sets with high offset values, and keyset pagination is possible, the API enforces the use of the next parameter for pagination instead of offset. It is highly encouraged to use next instead of offset for all API interactions that require pagination when possible.

Responses contain a _metadata section that includes total number of records available and pagination parameters used in the request:

{
  "_metadata": {
    "collection": "people",
    "offset": 50,
    "limit": 25,
    "total": 1000,
    "next": "eyJzaW5jZUlkIjoxMDV9",  
    "nextLink": "https:\/\/api.followupboss.com\/v1\/people?limit=25&&next=eyJzaW5jZUlkIjoxMDV9"
  },
  "people": [
    {
      "id": 950,
      "created": "2012-04-23T02:23:11Z",
      ...
    },
    {
      "id": 949,
      "created": "2012-04-22T02:23:11Z",
      ...
    },
    ...
    {
      "id": 926,
      "created": "2012-04-19T02:23:11Z",
      ...
    }
  ]
}

Example

Return the third page of most recently created people with 25 people per page:

GET /v1/people?offset=50&limit=25