RE: Call for consensus for the pagination design (ISSUE-42)

On Saturday, October 24, 2015 4:25 PM, Karol Szczepański wrote:
> I understand exactly what this consesus is about. I’m just trying to
> throw few real life scenarios to probe whether the concept is bullet
> proof. If we decide on something just to modify it in 2 months later I
> acknowledge that as a failure.

+1


> I’m just pragmatic – I know what kind of troubles I had so far while
> using hydra, especially in build business apps.

Thanks for sharing your experience.


> Just by getting back to the Markus’ example (rewritten in turtle – it
> talks more to me than JSON-LD):
> 
> GET /an-issue/comments?page=3 –>
> </an-issue/comments?page=3> a hydra:PartialCollectionView ;
>     hydra:first </an-issue/comments> ;
>     hydra:previous </an-issue/comments?page=2> ;
>     hydra:next </an-issue/comments?page=4> ;
>     hydra:last </an-issue/comments?page=498> .
> <http://api.example.com/an-issue/comments> a hydra:Collection ;
>     hydra:member <some_member_1>, <some_member_2> ;
>     hydra:view </an-issue/comments?page=3> .
> 
> In this example:
> - there is no direct connection between the partial view and the
> collection itself (unless hydra:view is symmetric) as there is no
> inverse property defined yet (i.e. hydra:isViewOf)

Depends on what you mean by "direct connection". There's the

  </an-issue/comments> hydra:view </an-issue/comments?page=3> .

triple which directly connects the collection to the view. I consider inverse properties as an anti-pattern. There's no need to materialize an inverse property. It is easier to have to look for just a single one instead of two.


> - there is however a connection between the collection and it’s partial
> view (one of them!)

Yes, in this representation you got one of them and the reason for that is because you just got a partial representation of the collection. That's the underlying design idea.


> - each request to different view will modify the original collection by
> providing different members to the collection’s IRI; client could imply
> that the collection changes on every request – I’ve got problem with that

That's true. If it weren't defined differently, the client could indeed assume that. We are, however, writing a specification and it exactly defines how a client has to interpret such data. If the client doesn't respect the specification, all bets are off anyway.


> - hydra:first points to the collection’s Url – client could imply that
> </an-issue/comments> a hydra:Collection, hydra:PartialCollectionView,
> which is not that bad
> - what if the server chooses the collection’s Url not to be a partial
> view?

This was an oversight when I wrote the example (Pavlik spotted it already). It should point to /an-issue/comments?page=1.
 
> imagine the client ends up in the collection’s Url (i.e. from
> bookmark, doesn’t matter how) – the only way to tell the client on how
> to get to the view is to add hydra:view </an-issue/comments?page=1>
> (assuming that this is the first page). How does it differ from adding
> hydra:first </an-issue/comments?page=1>?

Well, obviously if the server decides to paginate, it has to tell the client. The mechanism to do so, is hydra:view.

> This way we may end up that
> each collection may be a view of itself! Actually I’m keen to agree
> with that as the collection’s Url is somehow a virtual RDF resource
> exposes for the sake of ReSTful approach and by definition is a view
> of something else
> - how to tell the client on the API documentation level what the
> collection’s url actually returns? a collection? members of type X? a
> collection of members of type X?

Currently you would say it returns a hydra:Collection. I think it would be valuable to be able to express of what type (or shape) the members of the collection are as well.


> - how to tell the client on the API documentation level on what are
> other views? pointing only to the first page at that level is
> irrelevant – client will need either to follow links on each request
> making the API documentation obsolete or download everything if possible
> and do the rest on it’s own again making a documentation obsolete

We will discuss this separately, most likely as part of the discussion of operations. ISSUE-42 (the one we are trying to close as result of this call for consensus) is about the representation of paginated collections. The modification (or client-initiated selection) thereof will be discussed separately. The reason why I want to keep the discussion really focused is because we got stuck on ISSUE-42 for way too long. Let's move forward step by step without losing sight of the bigger goals and requirements.


> Finally, I think that the modified example below is more accurate than
> the original:
> 
> GET /an-issue/comments?page=3 –>
> </an-issue/comments?page=3> a hydra:PartialCollectionView ;
>     hydra:first </an-issue/comments?page=1> ;
>     hydra:previous </an-issue/comments?page=2> ;
>     hydra:next </an-issue/comments?page=4> ;
>     hydra:last </an-issue/comments?page=498> ;
>     hydra:isViewOf </an-issue/comments> ;
>     hydra:member <some_member_21>, <some_member_22> .
>
> Using hydra:member here might imply that the PartialCollectionView is
> a subclass of Collection, which is not that bad at all.

Apart from the fact that you associated the member to the view and not the collection it is effectively exactly the same. We had this design with PagedCollection but run into problems exactly due to the fact that the members are not associated a single, overall collection. Unless you can provide some new insights or arguments why we should go back to the previous design, I think that ship has sailed.


> I waited for that discussion and before stating an agreement on
> something please take time to consider all pros, cons and possible
> use cases from various areas.

I certainly do... in this specific case we have been discussing various design for almost 8 months now. I think we have a good understanding of the issues and requirements and came up with an elegant design for it. While it doesn't reflect all specific use cases people brought forward, it is generic and extensible enough to be easily extended in the near future to change that.

So, to summarize it, unless someone presents some new insights or arguments against the proposed design, I think we should go ahead and declare victory. We can then either move on to the next item or start a separate discussion on how to extend it if people are interested to do so right ahead.


Cheers,
Markus


P.S.: I just realized that my two other mails didn't go out till today. I think you can mostly ignore them by now. Sorry.


--
Markus Lanthaler
@markuslanthaler

Received on Monday, 26 October 2015 20:10:43 UTC