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

Hi Ruben

>>>> 1. What response body should be returned for 
>>>> http://api.example.com/an-issue/comments request? With "view" or 
>>>> without it?
>>> I would say: the body of http://api.example.com/an-issue/comments?page=1
>>> with a Content-Location of 
>>> http://api.example.com/an-issue/comments?page=1.
>> Well, that's an option. Personally I prefer to return full body as client 
>> did not state any specific view (page in this scenario).
>Up to the server to decide then I'd say;
I agree

>>>> what defines how many items per page there is?
>>> The server, like anywhere else on the Web.
>> Ugh, this is all wrong. Indeed server may provide defaults, but in UI 
>> applications users may have possibility to state exactly how many items 
>> on page they want.
>The latter seems to be the exception.
>Few of the sites I know offer this option.
Sites not, business applications does.

>>> We should verify that the proposed paging is not incompatible with it,
>>> but I don't see any problems with the view-based model.
>> Indeed, my concerns are only towards naming. If we're stick to paging 
>> only we may end up with terms strictly bound to that concept and I 
>> acknowledge few more cases than paging.
>Paging seems a very flexible concept to me.
>Any concrete cases we cannot solve with paging?
Well, filtering and sorting does create views which are complementary for 
paging. You can imagine a search results and sorted collection not to be 
paged and opposite. You can mix all of these features altogether and you can 
have them completetly independent.

>> I think inconsistencies between views when no data change is present may 
>> proove problematic for client side implementations (i.e. from performance 
>> point of view).
>We should specify that paging should be consistent if the data doesn't 
>change.(Consistent with regard to some order.)
Exactly. I think spec should mention that

>>> We don't need to make this work for non-RDF representations as far as 
>>> I'm concerned;
>>> doing so would severely limit what we can do.
>> We should. Again, hydra not being able to handle non-RDF payloads will be 
>> it's nail to the coffin.
>I did not say it should not handle these;
>just that we not necessarily need to page non-information resources.
Plain old JSON structures with correct description becomes really 
informative :). As I said, there is not to much of work needed to adopt 
hydra to describe non-RDF structures. Also scenarios when a collection is 
i.e. of string labels - you can page these while each label itself is not 
RDF but still can be a view of an RDF relation to a given resource. Imagine 
API:
http://temp.uri/users/1/roles -> returns collection of string literals being 
role names of a given user of id = 1.
You can page/sort/filter these effectively creating various views of same 
data.

>>> What aspects of paging would be necessary to detail in the API 
>>> documentation?
>> Well, it's more related to cardinality issues and iri templates.
>Okay, but nothing paging-specific then?
Well, how wou you tell the client that a given operation is pageable? I 
could image i.e. an iri template:
http://temp.uri/user?page={page} with mapping to hydra:page (or whatever 
predicate we would end up), but there is nothing in the spec now regarding 
that.

Best,

Karol

Received on Tuesday, 20 October 2015 21:04:34 UTC