Re: Pagination - let's finalize the collection design (ISSUE-42)

Hi Markus,

we are currently implement an offset based pagination scheme using
the existing hydra terms this looks something like this:

"@type": "PagedCollection",
"totalItems": 342,
"itemsPerPage": 100,
"firstPage": "/elements/",
"lastPage": "/elements/?offset=300",
"nextPage": "/elements/?offset=100"
...

As far as I can see, this would be also possible with the view based 
approach.
The only question for me is what about `totalItems` and `itemsPerPage`.
Do you propose to drop them or translate them to the view based model?

Of course there are cases where you cannot determine them
but this is not an issue as nothing needs to be mandatory returned by a 
RESTful server.

Speaking of use-cases... what about changing the size of the view
(the number of items shown in the view). I think we have never discussed 
this before.
I can imagine a IRI template based link for this whose property _might_ 
also
make sense in Hydra.

BG, Thomas

Am 11.10.2015 um 22:52 schrieb Markus Lanthaler:
> Hi folks,
>
> As announced, I would like to finalize the collection design as the next
> step. We made great progress on collections in general a couple of months
> ago but got stuck when it came to pagination. We discussed a number of
> proposals [1] but couldn't find a solution so far that everyone could live
> with.
>
> I spend quite some time thinking about this and looking at it from different
> angles and think I found an approach we haven't discussed yet. The main
> difference to the other proposals is to 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. This either might sound like a minor
> detail or, depending on where you are coming from, as a strange way of
> looking at things. I think, however, that is a semantically sound approach
> that has some nice advantages over the alternatives considered so far - not
> the least that the approach nicely generalizes to other use cases.
>
> The representation of a specific view on the collection could look somewhat
> like this:
>
>    {
>      "@id": "http://api.example.com/an-issue/comments",
>      "@type": "Collection",
>      "member": [ ... ],
>      "view": {
>        "@id": "/an-issue/comments?page=3",
>        "@type": "PartialCollectionView",
>        "first": "/an-issue/comments",
>        "previous": "/an-issue/comments?page=2",
>        "next": "/an-issue/comments?page=4",
>        "last": "/an-issue/comments?page=498",
>      }
>    }
>
> Please note that the collection members are directly associated to the
> collection itself, not the view. This means that there's no need to
> separately tie back each member of the collection to the collection itself.
> A page is a specific view on the collection and has its own URL. That means
> that it is possible to point to both the complete collection as well as a
> specific view. It also opens the door to define views which are defined in
> terms of an offset and limit instead of a server defined "page".
>
> I deliberately didn't use "page" or "pagination" in the name of the type of
> this view (PartialCollectionView). The reasoning behind this is the
> discussion we had about the meaning of "first" links on a page (what do they
> mean?). I think talking about views on something acknowledges the fact they
> have to been seen in the larger context and they do have "knowledge"
> thereof. As such, I don't see a problem that they refer to the
> first/previous/next/last partial view of a collection. The first and last
> link are obviously optional. The first view can be obtained by going to the
> collection itself. The last view has been reached when there's no more next
> link.
>
> Before we start discussing the naming of these concepts, I would like to get
> a sense of how the overall approach and the concepts it uses is perceived.
> Does it make sense to you? Is it easily understandable? Is anything missing?
>
>
> Cheers,
> Markus
>
>
> [1] http://www.w3.org/community/hydra/wiki/Pagination
>
>
>
> --
> Markus Lanthaler
> @markuslanthaler
>
>

Received on Wednesday, 14 October 2015 15:49:13 UTC