Collection Pagination

Most collections support pagination, which allows you to fetch a subset of all of the items in the collection. The subset of items is a page, and you can set how many items to include in a page. Pagination also involves fetching subsequent pages. Apiture Open APIs supports multiple user experiences, including traditional page scrolling and “infinite scrolling” (dynamic loaded on-demand content). Avoid patterns of use which result in expensive fetching of most or all resources in large collections. Combine pagination 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.
limit integer The requested page size; the maximum number of items to return in a page.

Whether you pass these two parameters or not, start and limit are always returned in the collection representation to identify which page is returned.

A service may return fewer items if the number of results is less than the limit, or if the limit exceeds a maximum page size for the collection. For example, even if there are 5 billion resources in a collection, a 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 the following 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 the default filter and sort criteria.