Implementing Link Header Pagination

[Ricardo Rezende]

In the past few years, more and more APIs have begun to follow the RFC5988 convention of using the Link header to provide URLs for the next page.

An API that uses the Link header can return a set of ready-made links so the API consumer doesn't have to construct links themselves. This is especially important when pagination is cursor based. Here is an example of a Link header used properly, grabbed from GitHub's documentation:

Link: https://api.github.com/user/repos?page=3&per_page=100; rel="next",
https://api.github.com/user/repos?page=50&per_page=100; rel="last"

next - shows the URL of the immediate next page of results.
last - shows the URL of the last page of results.
first - shows the URL of the first page of results.
prev - shows the URL of the immediate previous page of results.

The response includes also additional information about pagination like total entries and total pages.

Example headers:

X-Total-Entries: 60
X-Total-Pages: 2