Collection Pagination
Most resource collections support pagination, which allows you to fetch a subset of all of the items in the collection. The subset of items is called a page. You can set a limit
to how many items to include in a page.
Subsequent pages can be displayed to the user with traditional page scrolling or dynamic loaded, such as for infinite scrolling. Programs should avoid calling for and gathering large collections of resources all at once. Combine pagination with filtering to return subsets of the data that the client is interested in and needs.
nextPage_url
provides the URL of the next page in the collection. Pagination can only be navigated in a forward, linear direction.
A page is identified with two query parameters:
Property | Type | Description |
start | string | The opaque cursor that specifies the starting location of this page of items. It is not a page number. If omitted, the default is the beginning of the collection. |
limit | integer | The requested page size; the maximum number of items to return in a page. |
The start
field is returned within the nextPage_url
link in a collection, if there are more items in the collection. Clients do not define the value of the start
parameter.
The limit
is 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. The service will restrict the page contents to items the user is authorized to view.