Rethink paging

[RubenVerborgh]

As discussed on the mailing list, the current implementation of paging might be confusing. This became apparent when I was implementing this for the Linked Data Fragments server (try the Turtle or JSON-LD representaiton).

Basically, the whole misconception for me comes with the term PagedCollection. If I told you "x is a paged collection", what would you expect? That x is a single page or that x is a collection that is accessible as pages?
Hydra says that a PagedCollection is a page, as is apparent from the current spec:

// EXAMPLE 14: A Hydra PagedCollection splits a collection into multiple pages
{
  "@context": "http://www.w3.org/ns/hydra/context.jsonld",
  "@id": "http://api.example.com/an-issue/comments?page=3",
  "@type": "PagedCollection",
  "totalItems": "4980",
  "itemsPerPage": "10",
  "firstPage": "/an-issue/comments?page=1",
  "nextPage": "/an-issue/comments?page=4",
  "previousPage": "/an-issue/comments?page=2",
  "lastPage": "/an-issue/comments?page=498",
  "member": [

  ]
}

This seems like a misnomer. What can we do to fix? Suggestions in comments.

---

BTW @lanthaler I would be totally willing to write this into the spec.

[RubenVerborgh]

Suggested solution: Introduce Page

Introduce Page as a result page of a collection:

// The collection itself
{
  "@context": "http://www.w3.org/ns/hydra/context.jsonld",
  "@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",
}

// A page of the collection
{
  "@context": "http://www.w3.org/ns/hydra/context.jsonld",
  "@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": "http://api.example.com/an-issue/comments",
}

Note the redefinition of the properties:

• firstPage relates a Collection to a Page
• lastPage relates a Collection to a Page
• nextPage relates a Page to a Page
• firstPage relates a Page to a Page

And the introduction of two new properties:

• hasPage relates relates a Collection to a Page
• pageOf relates relates a Page to a Collection

Additionally, we might redefine the type PagedCollection to apply to those collections that are available in a paged way.

[elf-pavlik]

+1 introducing hydra:Page more details in email: http://lists.w3.org/Archives/Public/public-hydra/2014Oct/0002.html

how about:

• PagedCollection SHOULD embed it's first Page

   {
     "@id": "/collection",
     "@type": "PagedCollection",
     "totalItems": 243,
     "itemsPerPage": 10,
     "firstPage": {
       "@id": "/collection?page=1",
       "@type": "Page",
       "member": [ "1", "2", "..." ],
       "nextPage": "/collection?page=2",
       "pageOf": "/collection"
     },
     "lastPage": "/collection?page=24"
   }

• Page SHOULD embed PagedCollection it belongs to

   {
     "@id": "/collection?page=1",
     "@type": "Page",
     "member": [ "1", "2", "..." ],
     "nextPage": "/collection?page=2",
     "pageOf": {
       "@id": "/collection",
       "@type": "PagedCollection",
       "totalItems": 243,
       "firstPage": "/collection?page=2",
       "lastPage": "/collection?page=24"
       "itemsPerPage": 10
     }
   }

using PagedCollection (subclasOf: Collection) for fristPage and itemsPerPage

[ceefour]

What about CollectionPage? Just for the sake of avoiding naming "conflicts". Page is overloaded... we already have WebPage...

[akuckartz]

Please consider #36 while rethinking paging.

[lanthaler]

Proposals are being tracked at https://www.w3.org/community/hydra/wiki/Pagination

[lanthaler]

PROPOSAL: Look at pages of a collection as specific views on a single underlying collection instead of thinking of the collection as the sum of its pages. More concretely,

• replace PagedCollection with PartialCollectionView,
• replace firstPage/nextPage/previousPage/lastPage with first/next/previous/last,
• associate totalItems with Collection instead of PagedCollection, and
• remove itemsPerPage for the time being (we will likely re-introduce it with a different name).

[lanthaler]

Call for consensus: https://lists.w3.org/Archives/Public/public-hydra/2015Oct/0163.html

[lanthaler]

RESOLVED: Change the current pagination design by replacing PagedCollection with PartialCollectionView, replacing firstPage/nextPage/previousPage/lastPage with first/next/previous/last, associating totalItems with Collection instead of PagedCollection, and removing itemsPerPage.

[tpluscode]

I've just noticed that the wiki page is outdated. Should it be deleted?

[akuckartz]

@tpluscode It does not seem to be optimal to use a comment in this closed issue for that question.

[lanthaler]

It isn't outdated (This page collects design proposals for ISSUE-42 - it still does). We should keep stuff around to document what we did.

[tpluscode]

Fair enough. But the page doesn't say that the issue has been closed. One could get the impression that the design still hasn't been decided on

[nicksloan]

I just wanted to mention that today I found that wiki page and wondered myself if the discussion had been resolved or not. Glad to see it has, as I think that PartialCollectionView is a great way to handle this, but I do think the wiki should be updated to indicate resolution. Adding a note to the top of the document would preserve the discussion, but also help to avoid confusing people new to Hydra.