This is a draft that could be altered, removed or replaced by other documents. It is not a recommendation approved by TO.
Conformance
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY and MUST in this document
are to be interpreted as described in
BCP 14
[RFC2119] [RFC8174]
when, and only when, they appear in all
capitals, as shown here.
Abstract
This document is part of the Nederlandse API Strategie.
Resource collections can be unreasonably large for a single response.
With pagination, a segment of the resources can be returned while providing a method to retrieve other segments (or "pages").
This module provides design rules which attempt to strike a balance between enhanced predictability for clients and flexibity to suit different data collection types.
A distinction between two categories of collections is used throughout this module: static and dynamic.
1.1 Static collections
Static collections are stable or at least unlikely to change while a client is retrieving segments of the resources.
Page-number pagination would suffice for these collections.
If no mutation occured between retrieving pages, sequential pages will have no gaps or overlap, e.g. if item no. 100 is the last of a page, item no. 101 will be the first item on the next page.
If a resource collection is not completely static, no pagination method is reliable for synchonisation.
1.2 Dynamic collections
Dynamic collections see frequent mutations.
While a client jumps from one page to the next an item may have been inserted or removed in the previous pages causing a shift that results in an overlap or a gap, respectively.
At the cost of complexity, cursor pagination is more robust by providing a pointer to a listed item for page boundaries which remain consistent even if collection shifts.
1.3 Pagination formats
In order to support both collection categories, this module allows two pagination formats: page-number pagination (using page and pageSize) and cursor pagination (using cursor and limit).
2. Design rules
2.1 Summary
Design rules are technical rules, which should be tested automatically, and functional rules, which should be considered when designing and building the API.
