Pagination - Version 1.0-rc4 🔗

This document describes a mechanism by which a server can return a set of records to a client in an incremental fashion. Often this will be used when a client is doing a query for a set of records and the result set is too large to return in one response.

Notations and Terminology 🔗

Notational Conventions 🔗

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.

Client Request 🔗

When a client sends a request to a server which is meant to result in a set of records being returned, the client MAY include extra attributes to control how those records are to be returned if the results can not fit within one response message.

Client Attributes 🔗

The following list of attributes MAY be included in a client's request for a set of records from a server. The client MUST only specify these on the initial request for the set and their presence (and values) in any subsequent request to the server to retrieve additional records for the same pagination sequence is dictated by the server - the client MUST NOT add or modify them.

While this specification defines a mechanism by which clients can initiate the pagination of a result set, servers MAY automatically initiate it themselves, typically if the result set is very large. How the server knows that the client supports pagination, or how clients are made aware of this possibility, is out of scope for this specification.

The location and syntax of how these attribute appear in request messages will be defined by the protocol binding being used.

limit 🔗

Server Response 🔗

When a server returns a subset of records, it MAY include additional attributes to help the client retrieve the additional subsets of records.

Server Attributes 🔗

The following list of attributes MAY be included in a server's response to a client's request for a set of records. The location and syntax of how these attribute appear in response messages will be defined by the protocol binding being used.

Note: in the examples listed below, the use of certain query parameters in the sample response message's Link URL, such as pos, is an implementation detail of the server. How the server encodes the information it needs to retrieve a certain subset of records is not mandated by this specification.

rel 🔗

expires 🔗

count 🔗

offset 🔗

limit 🔗

HTTP Binding 🔗

The following describes how the attributes defined above would appear in a flow of HTTP messages during the retrieval of a set of records.

Request for a record set 🔗

To request a set of records from a server, a client will send an HTTP GET request to the server. How this URL is determined is out of scope of this specification.

The client MAY include the limit attribute as part of this request. Unless there is some out-of-band negotiation to determine a different mechanism, the server MUST accept the limit attribute as a query parameter (named limit, case sensitive) in the URL.

Example:

http://example.com/people?limit=100

Response for a record set 🔗

Each successful response from the server MUST adhere to the following:

Links in server response messages MUST appear as HTTP headers using the format described in RFC8288, and adhere to the following form:

Link: <URL>;rel=STRING;offset=UINT;limit=UINT;count=UINT

Where:

Example:

Initiate a pagination request, asking for only 10 records per response:

GET http://example.com/?limit=10

The first response in the sequence of 100 items might look like:

HTTP/1.1 200 OK
Link: <http://example.com?seq=29182>;rel=first
Link: <http://example.com?seq=29182s>;rel=self;offset=0;limit=10;count=100
Link: <http://example.com?seq=29182n>;rel=next
Expires: Wed, 01 Dec 2021 16:00:00 GMT

... first 10 records ...

and the 2nd request might look like:

GET http://example.com?seq=29182n

The response might look like:

HTTP/1.1 200 OK
Link: <http://example.com?seq=29182>;rel=first
Link: <http://example.com?seq=29182>;rel=prev
Link: <http://example.com?seq=29182s>;rel=self;offset=10;limit=10;count=100
Link: <http://example.com?seq=29182n>;rel=next
Expires: Wed, 01 Dec 2021 16:00:00 GMT

... second 10 records ...

If the complete result set was only 5 records, then only the self Link header might included in the first response:

Link: <http://example.com?seq=29182>;rel=self;offset=0;limit=10;count=5

Iterating over the record set 🔗

Once the record set retrieval has started, the client MAY use the Links returned from the server to iterate through the full set of records. Typically, the client will use the next Link from each response to retrieve the next subset of records until a response is returned without a next Link - indicating that it has reached the end.

For each record set returned, typically, the client will use the self Link's metadata in any end-user facing interfaces to indicate which page they are viewing. For example, using the above example's 2nd response's metadata:

Showing: 11-20 of 100 records

However, if other Links are provided by the server, then the client MAY use those Links instead to follow a different traversal path through the records.