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

// Gather up to 10 pages of members from the events collection
const events = await hydraClient.getResource("http://example.com/api/events");
let data = PartialCollectionCrawler.from(events);
for (const member of await data.getMembers({ requestLimit: 10 })) {
    // do something with the *member*, i.e. display it
}

// Do the same thing on one-by-one basis
data = await hydraClient.getResource("http://example.com/api/events");
for (const member of data.members) {
    // do something with the _member_, i.e. display it
}
// load some more on demand
data = hydraClient.get(data.view.next);
for (const member of data.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": "PartialCollection",
    "manages": {
      "property": "rdf:type",
      "object": "schema:Event"
    },
    "next": "/api/events?page=2",
    "first": "/api/events",
    "last": "/api/events?page=2",
    "totalItems": 1,
    "member": [
        {
            "@id": "/api/events/1",
            "eventName": "Event 1",
            "eventDescription": "Some event 1",
            "startDate": "2017-04-19",
            "endDate": "2017-04-19"
        }
    ]
}

GET /api/events?page=2

HTTP 200 OK

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

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 });