To request a subset of a collection of resources, pagination can be used. You can use either offset-based pagination or date-based pagination.
Offset-based pagination uses the offset and limit parameters. These work on all collections,
but the downside is when new resources are added to the collection between the fetching of pages by
the client, you may get overlap in responses. If resources are removed between page fetches,
resources may be skipped by the pagination.
Date-based pagination uses at least one of the date_after, date_before, date_since or
date_until parameters and can be used to avoid the problems described with offset-based
pagination.
Note
date_after and date_before are exclusive, whereas date_since and date_until are inclusive.
It is possible to specify a date for both the beginning of the page and the end of the page, but it
is also possible to specify a single date property and combine it with the limit parameter.
| Name | Type | Description |
|---|---|---|
| date_after[ path ] | datetime | ISO 8601 compliant timestamp (including timezone) |
| date_before[ path ] | datetime | ISO 8601 compliant timestamp (including timezone) |
| date_since[ path ] | datetime | ISO 8601 compliant timestamp (including timezone) |
| date_until[ path ] | datetime | ISO 8601 compliant timestamp (including timezone) |
| limit[ path ] | integer | Maximum number of records to return |
| offset[ path ] | integer | Number of records to skip |
Adding a path to any of the parameters is optional. Without a path, the parameter applies to the main resource and any embedded collections. When a path is specified, it only applies to the collection referenced by the path.
property path = [ resource ], { ".", ? resource name ? } ".", ? property name ? ;
resource = "self" | ? resource name ? ;