Pagination (ISSUE-42)

Hi folks,

As announced (and promised) for a while, I would like tackle pagination
next. While implementing Linked Data Fragments, Ruben made an interesting
observation, namely that by just giving someone the URL of a
"PagedCollection" it is unclear whether it is a single "page" or a
"collection of pages". His proposal was to rename hydra:PagedCollection to
hydra:Page and to introduce two new properites hydra:pageOf and
hydra:hasPage. A paginated collection would then look as follows in JSON-LD 

  {
    "@id": "http://api.example.com/an-issue/comments?page=3",
    "@type": "Page",
    "previousPage": "/an-issue/comments?page=2",
    "nextPage": "/an-issue/comments?page=4",
    "pageOf": {
      "@id": "http://api.example.com/an-issue/comments",
      "@type": "Collection",
      "firstPage": "/an-issue/comments?page=1",
      "hasPage": "/an-issue/comments?page=4",
      "lastPage": "/an-issue/comments?page=498"
    },
    "member": [ ...]
  }

In contrast, with the current design it would look as follows

  {
    "@id": "http://api.example.com/an-issue/comments?page=3",
    "@type": "PagedCollection",
    "firstPage": "/an-issue/comments",
    "previousPage": "/an-issue/comments?page=2",
    "nextPage": "/an-issue/comments?page=4",
    "lastPage": "/an-issue/comments?page=498",
    "member": [ ...]
  }

The advantage of Ruben's proposal is that it becomes possible to address the
whole collection as well as individual pages. With the current design that's
not possible. The property referencing a PagedCollection would need to
define what is meant. The advantage is an overall simpler design that aligns
more closely with what developers are used from Atom or even HTML pages.

Another design I have been tinkering with was to rename PagedCollection to
something like PartialCollection and *perhaps* move the pagination controls
into a separate resource or blank node:

  {
    "@id": "http://api.example.com/an-issue/comments?page=3",
    "@type": "PartialCollection",
    "pagination": {
      "firstPage": "/an-issue/comments",
      "previousPage": "/an-issue/comments?page=2",
      "nextPage": "/an-issue/comments?page=4",
      "lastPage": "/an-issue/comments?page=498"
    },
    "member": [ ...]
  }


I would propose we collect alternative designs and then discuss all of them.
I created a Wiki page to collect the designs.

   https://www.w3.org/community/hydra/wiki/Pagination

If you have something to propose, please add it to the page but *also* send
it to the mailing list. I would say we collect designs till the end of the
week and start discussing them beginning of next week. I'm also open to
other proposals on how to address this process-wise.


Cheers,
Markus


--
Markus Lanthaler
@markuslanthaler

Received on Monday, 2 February 2015 22:48:48 UTC