Closed RubenVerborgh closed 8 years ago
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.
+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
What about CollectionPage
? Just for the sake of avoiding naming "conflicts". Page
is overloaded... we already have WebPage...
Please consider #36 while rethinking paging.
Proposals are being tracked at https://www.w3.org/community/hydra/wiki/Pagination
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,
Call for consensus: https://lists.w3.org/Archives/Public/public-hydra/2015Oct/0163.html
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
.
I've just noticed that the wiki page is outdated. Should it be deleted?
@tpluscode It does not seem to be optimal to use a comment in this closed issue for that question.
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.
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
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.
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 aPagedCollection
is a page, as is apparent from the current spec: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.