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

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 Sunday, 11 October 2015 20:52:56 UTC