3.2.pagination.md

Pagination

Story

As an API consumer I want to be able to retrieve partial collection views (pages) So that I can show first batch of items as soon as possible.

Example

As an application user I want to display first 10 events matching some criteria So I can start reviewing them with option of loading more on demand.

Usage

const client = new HydraClient();
let collection = client.get("/api/events");
for (const member of collection.members) {
    // do something with the _member_, i.e. display it
}
// load some more on demand
collection = client.get(data.view[0].next);
for (const member of collection.members) {
    // do something with more _member_, i.e. display it
}

Details

Client may discover that the resulting collection does not have all the members listed within the payload, thus further browsing may be required to obtain more (or all) members. Each payload should point the client to further parts of the collection by providing proper links, i.e. 'hydra:next'.

GET /api/events

HTTP 200 OK

{
    "@context": "/api/context.jsonld",
    "@id": "/api/events",
    "@type": "Collection",
    "manages": {
      "property": "rdf:type",
      "object": "schema:Event"
    },
    "totalItems": 1,
    "member": [
      {
        "@id": "/api/events/1",
          "eventName": "Event 1",
          "eventDescription": "Some event 1",
          "startDate": "2017-04-19",
          "endDate": "2017-04-19"
        }
    ],
    "view": [{
      "@type": "PartialCollectionView",
      "next": "/api/events?page=2",
      "first": "/api/events",
      "last": "/api/events?page=2"
    }]
}

GET /api/events?page=2

HTTP 200 OK

{
    "@context": "/api/context.jsonld",
    "@id": "/api/events?page=2",
    "@type": "Collection",
    "manages": {
      "property": "rdf:type",
      "object": "schema:Event"
    },
    "totalItems": 1,
    "member": [
      {
        "@id": "/api/events/1",
        "eventName": "Event 1",
        "eventDescription": "Some event 1",
        "startDate": "2017-04-19",
        "endDate": "2017-04-19"
      }
    ],
    "view": [{
      "first": "/api/events",
      "previous": "/api/events",
      "last": "/api/events?page=2"
    }]
}

In this situation, a client may be needed to traverse all the links provided in consecutive payloads to gather all collection members.

It may be useful to introduce a way to instruct the Hydra client to do so, i.e.:

let data = client.get("/api/events", { followPartialLinks: true });