Explaining Pagination Link Relations to API Consumers

An API that returns a collection may send only part of the matching data in one response, dividing it into pages through a method called pagination. To help a client move between them, the API can include links labeled next, prev, first, or last. These labels are called link relations: they describe how a linked page relates to the page the client has already received.

The client should follow the link for the page it needs and request the target the API provides. It should not guess another page’s URL by changing a page number, cursor (a value that marks a position in the collection), or offset (a count of items to skip). The API’s contract defines what links it supplies and any additional rules for following them.

What a pagination link tells the client

A link connects the current page, called its context, to another resource, called its target. The relation label describes how that target relates to the context. In a pagination response, the current collection page is the context, and the link points to another page. RFC 8288 defines this general Web Linking model.

An HTTP response can carry links in a Link header:

Link: ; rel="next"

Here, rel="next" labels the relationship, and the URI inside angle brackets is the target to request. This example uses a cursor in the URL, but the relation itself does not specify the cursor’s format or any other pagination parameter. APIs can also represent links in their response data. For example, JSON:API 1.1 defines pagination links in a JSON links object.

What each relation means

In a pagination contract, these relations identify positions in the sequence of pages:

The IANA link-relation registry defines the general meanings of these labels. The API’s contract or format says how to use these labels for pagination. JSON:API, for instance, assigns these relations to the first, previous, next, and last pages of a paginated collection. The registry also lists previous as a synonym for prev, while JSON:API uses the key prev. Follow the vocabulary the API documents.

A relation tells the client where the target sits in the series. It does not set the page size, explain how the server sorts results, or say what happens if the collection changes while the client moves through its pages. The API’s contract must cover those details.

Follow the advertised target

When a client needs another page, it should find the link labeled with the desired relation and request that link’s target. For example, to continue through a collection, the client requests the current page, finds next, requests its target, and repeats while a next link is present and the client still needs more results.

The target might contain a page number, a cursor, or another endpoint-specific value. The client should use the supplied target rather than incrementing a page number or editing a cursor. GitHub’s pagination documentation illustrates this approach and notes that pagination parameters can vary between endpoints.

Clients also need to handle the link format correctly. For an HTTP Link header, use a parser that understands its syntax. Do not split the header on commas or semicolons. Then select links by their relation labels. Ordering does not determine which link represents next or last.

Before automatically following a target, validate its destination against the API’s documented policy. In particular, do not send credentials to a URL with a different origin (scheme, host, or port) unless the API explicitly permits it. RFC 8288 warns that links in HTTP headers are not inherently trustworthy and discusses risks from automatic link following. A client that fetches pages in a loop should set limits for its task, such as a maximum page count, elapsed time, or response volume.

Missing links and changing collections

An API does not have to provide all four relations on every page. It might omit first or last, for example. JSON:API allows an unavailable pagination link to be omitted or represented as null; GitHub also documents cases where it omits links, including last when it cannot calculate that target. Treat the links actually provided as the available navigation instructions. The absence of last alone does not establish that no later data exists.

A link relation also does not guarantee that the collection remains unchanged while the client moves between pages. The general Web Linking standard defines link relationships, but it does not say whether pagination shows the same collection contents on every page. If records change while the client moves through pages, the API’s documentation must explain whether the client reads one fixed set of records (a stable snapshot) and what to expect when changes happen at the same time. Check that contract before assuming that moving through the pages returns every record in a changing collection without duplicates.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com