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

Hi Dietrich

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. I’m just pragmatic – I know what kind of troubles I had so far while using hydra, especially in build business apps.

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)
- there is however a connection between the collection and it’s partial view (one of them!)
- 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
- 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? 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>? 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?
- 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

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.

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.

Best regards

Karol Szczepański