How should a RESTful API handle pagination in the situation where a client may want the ability to jump to arbitrary pages? Let's assume we are using the Link
header in the way the GitHub API does:
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"
The API, like many others, returns links to the next page, previous page, first page and last page. This does not account for the relatively common use-case of providing on the client-side links to a range of pages, and not just the next/previous/first/last. If, for example, the request returns 100 pages worth of results, the client may want to allow the ability to jump to an arbitrary page. How should this be done while adhering closely to the concepts of REST?
Some possible options:
- Just let the client infer the other links. You have the first and last page, it may be a reasonable assumption to modify the link to obtain the other pages. This seems to go against HATEOAS (which is always the principle of REST that seems to cause problems).
- Return a link to every page. This seems unwieldy as the potential number of pages could be high.
- Return a link to a small range of pages (perhaps 2 either side of the current page). This seems like a relatively sensible approach but it limits the options clients have when it comes to displaying pagination information.
?page=3&per_page=100
. So I'd say you have the ability to jump to anywhere you want.