Fork me on GitHub

If I have a (large) collection of resources, how can I supply a client with a paginated list?

Don't use custom pagination systems like adding a page number to the URL or query string. Instead, use link relations.

GET /collection HTTP/1.1

HTTP/1.1 200 OK
<collection>
    <article id="1">...</article>
    <article id="2">...</article>
    <article id="3">...</article>
    <article id="4">...</article>
    <article id="5">...</article>
    <meta>
        <link rel="self" href="/collection" title="Current page"/>
        <link rel="next" href="/collection/2" title="Next page"/>
        <link rel="first" href="/collection/1" title="First page"/>
        <link rel="last" href="/collection/5" title="Last page"/>
    </meta>
</collection>

If the client want to browse through the next set of collections, it can do so by following the "next" relation link. These are defined by IANA as standard relations

See also

Caveats

  • Even though it's tempting to create your own pagination scheme by "building" URLs, you should only use the information given by the API. This means, you cannot assume that the 3rd page can be found at /collection/3. If you do, your client will break as soon as the API changes its pagination behaviour.

Topics