HTTP for API Transport
Resources and URI Structure
Hypermedia Application Language (HAL)
Representation Profiles and Schemas
Optimistic Locking and Concurrency
Error Responses and Error Representation
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:
||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
||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
By using the service-supplied links, the client does not have to perform any arithmetic to compute the next
||The next page in the collection, using the same filter and sort criteria|
||The previous page in the collection, using the same filter and sort criteria (Warning this link may be removed in future releases)|
||The first page in the collection (resets
||The last page in the collection, using the same filter and sort criteria (Warning this link may be removed in future releases)|
||The first page in the collection, using default filter and default sort criteria|