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, MUST, and SHOULD 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 flexibility 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 occurred between retrieving pages, sequential pages will have no gaps or overlap, e.g. if item n is the last of a page, item n+1 will be the first item on the next page.
If a resource collection is not completely static, no pagination method is reliable for synchronisation.
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 the 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.
The OpenAPI definition document MUST include a default value for the returned page size (pageSize or limit) through the query parameter's schema, with integer as type and a default key.
The schemaSHOULD also include a maximum value. A requested value larger than the maximum MUST result in HTTP status code 400 (Bad Request).
Rationale
By documenting a default, the client can rely on that limit without having to request one or infer it from the presence of a link to another page.
By documenting a maximum, the client can avoid sending an unreasonable request.
A Link header provides clients with a convenient and consistent method of navigation.
The link relation type last is optional, as determining it requires counting the collection, which can be a costly endeavour.
Dynamic collections, like feeds, can experience mutations at the head. These can cause inconsistency with page alignment when reached with prev. Therefore, the backwards link is merely optional for cursor pagination.
An absent link relation allows the client to recognise the limits of the collection, without having to resolve a value without a target.
