Pagination
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
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
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.
CUSTOM-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.
Query Parameters
| 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 parameters applies to the main resource and any embedded collections. When a path is specified, it only applies to the collection referenced by the path.
Pagination support by message type
| Message type | Date | Offset | Comment |
|---|---|---|---|
| Private conversation[/networks/EID/messages/?conversation=EID] | ✓ | ✗ | |
| Comment[/networks/EID/messages/?parent=EID] | ✗ | ✓ | |
| Announcement[/networks/EID/announcement] | ✗ | ✓ | |
| File[/networks/EID/recentfiles OR /networks/EID/messages/?parent_folder=EID] | ✗ | ✓ | |
| Task[/networks/EID/tasks/] | ✗ | ✓ | |
| Event[networks/EID/events/] | ✓ | ✓ | Date filter keys are start_from(datetime) and start_before(datetime) |
| Event(past)[/networks/EID/events/past/] | ✓ | ✓ | Date filter keys are start_before_or_at(datetime) and last_seen_eid(EID) |
| Poll[/networks/EID/messages/?type=poll] | ✓ | ✗ | |
| News[/networks/EID/news/] | ✓ | ✗ |
Syntax
property path = [ resource ], { ".", ? resource name ? } ".", ? property name ? ;
resource = "self" | ? resource name ? ;