Skip to main content

IPA-110: Pagination

APIs often need to provide collections of data, most commonly in the List standard method. However, collections can often be arbitrarily sized and also often grow over time, increasing lookup time as well as the size of the responses being sent over the wire. Therefore, collections must be paginated.

State

Adopt

Guidance​

  • APIs returning collections of data must provide pagination at the outset, as it is a backward-incompatible change to add pagination to an existing method
    • APIs should return collections within an Paginated prefixed envelop object
  • The request should support an integer itemsPerPage query parameter allowing users to specify the maximum number of results to return
    • itemsPerPage must not be required
    • If the user does not specify itemsPerPage (or specifies 0)
      • The API must not return an error and chooses an appropriate default (>= 1)
    • If the user specifies itemsPerPage greater than the maximum permitted by the API
      • The API should coerce down to the maximum permitted page size
    • The API may return fewer results than the number requested (including zero results)
  • The request should support an integer pageNum query parameter to allow the user to skip results
    • pageNum must not be required
    • If the user does not specify pageNum (or specifies 0)
      • The API must not return an error and chooses an appropriate default of 1
      • The offset (skip) must be calculated as (pageNum - 1) * itemsPerPage
  • The request may support a boolean includeCount query parameter to allow the user to omit the totalCount return value
    • includeCount must not be required
    • If the user does not specify includeCount
      • The API must not return an error and chooses an appropriate default of true
  • The response for collections must define an array of results containing the paginated resource
  • The response for collections should define an array of links field, providing the user with links to the next and previous pages
    • A next page link must only be included if there’s a next page available or if the service cannot determine if the end of the collection has been reached
    • A previous page link must be included if there's a previous page available
  • The response for collections may provide an integer totalCount field, providing the user with the total number of resources available in the backing collection
    • This total may be an estimate, but the API should explicitly document that

Example

GET /groups/${groupId}/clusters[?pageNum=${pageNum}][&itemsPerPage=${itemsPerPage}][&includeCount=${includeCount}]
{
  "links": [...],
  "results": [...],
  "totalCount": 0
}

Total count considerations​

Historically APIs defaulted to true on includeCount but calculating the total count for large collections can be computationally expensive.

  • API producers should exercise caution when introducing support for includeCount