Collection Pagination

Most collections support pagination which allows clients to fetch a subset of all the item in the collection; this small subset is a page of resources. Pagination then involves fetching subsequent pages. This supports multiple user experiences, including traditional page scrolling and “infinite scrolling” (dynamic loaded on-demand content). Applications should avoid patterns of use which result in expensive fetching most or all resources in large collections. Pagination should be combined with filtering to return subsets of the data that the client is interested in.

A page is identified with two query parameters:

Property Type Description
start integer The start index of the first item within the desired page of items. This is a zero-based index: the first item in the collection is at index 0. Note: This is not the page number. The default if omitted is 0. Warning This may change to be a string, to allow cursor-based pagination instead of integer page indexing.
limit integer The requested page size; the maximum number of items to return in a page.

These values are also returned in the collection representation to identify which page is returned.

The service may return fewer items if there are less that limit items in the collection, or if limit exceeds a maximum page size for the collection. For example, even if there are 5 billion resources in a collection, the service may impose a maximum of 2,500 items at a time. Also, the user may not have permission to view all resources; the service will restrict the page contents to items the user is authorized to view.

When a client fetches a collection, the response may contain collection links in the _links object. By using the service-supplied links, the client does not have to perform any arithmetic to compute the next ?start= offset.

Link relation Description
next The next page in the collection, using the same filter and sort criteria
prev The previous page in the collection, using the same filter and sort criteria (Warning this link may be removed in future releases)
first The first page in the collection (resets start to 0), using the same filter and sort criteria
last The last page in the collection, using the same filter and sort criteria (Warning this link may be removed in future releases)
collection The first page in the collection, using default filter and default sort criteria