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

Hi

Let me throw few more questions to the table. Assuming example (I'm 
following Carlos Melo's suggestion to replace PageCollection name to 
something view and not only paging related name):
{
    "@id": "http://api.example.com/an-issue/comments",
    "@type": "Collection",
    "member": [ ... ],
    "totalItems": 4798,
    "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",
    }
}

1. What response body should be returned for 
http://api.example.com/an-issue/comments request? With "view" or without it?
I'd leave default unmodified result as is (but still it might a subject for 
server to decide). Still, we'd need to tell the client that while the 
default result (which may be still considered a view which overlaps the 
whole "collection") is not paged, there is still possibility of doing so. 
Maybe this would be enough:
{
    "@id": "/an-issue/comments",
    "@type": ["Collection", "CollectionView"],
    "member": [ ... ],
    "totalItems": 4798,
    "view": { "@id": "/an-issue/comments" }
    "first": "/an-issue/comments?page=1",
    "last": "/an-issue/comments?page=48",
}

2. I think agreeing on general approach of a view is not enough. We should 
already have some consensus on how to drive the view itself - what defines 
how many items per page there is? What is the order of members? Are there 
any other view modifiers in force, i.e. search terms, etc?
These get quite important as we didn't decide on how the server should 
handle these situation, i.e. I think it's a healthy assumption that server 
must guarantee that the order won't change between consequtive calls to same 
paged view. I'm not keen to maintain that assumption for unpaged 
view/collection.

3. While having in mind non-RDF responses (or we wouldn't like to put that 
information into RDF body), how are we going to express the view i.e. via 
headers? I was thinking to stick to general rules RFC 2616 defines when it 
comes to content range and range units. Maybe something like example below 
would work (including RFC 5988 web linking):
GET /an-issue/comments?page=1
Accept-Ranges: members
---
Content-Range: members 1-10/4798
Link: <http://api.example.com/an-issue/comments?page=1>; rel="first"
Link: <http://api.example.com/an-issue/comments?page=2>; rel="next"
Link: <http://api.example.com/an-issue/comments?page=48>; rel="last"

GET /an-issue/comments
Accept-Ranges: members
---
Content-Range: members 1-4798/4798
Link: <http://api.example.com/an-issue/comments?page=1>; rel="first"
Link: <http://api.example.com/an-issue/comments?page=48>; rel="last"

members range unit alludes hydra:member, link relations seems to be 
equivalent to hydra ones.

4. View approach presented discussed here is a hypermedia control within RDF 
body. I'd like also to take care of the api documentation equivalent.

Best

Karol

Received on Tuesday, 20 October 2015 17:06:50 UTC