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

Hi Ruben

Thanks for hasty reply.

>> 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).

>>   "@type": ["Collection", "CollectionView"],
>This would confuse two different resources (collection / page).
Well, I prefer to acknowledge full collection also as it's view (a special 
case).

>> 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. I've implemented many applications with that approach. I'm 
currently trying to implement a generic angularJS client application with 
automatically generated views based on API documentation and I also aim to 
have that feature covered. Indeed that feature is not always necessary (i.e. 
phones browsers where button with "more" is enough), but large screen 
devices (tablets, desktop) may want to present fully fledged configurable 
pager.

>> What is the order of members? Are there any other view modifiers in 
>> force, i.e. search terms, etc?
>For now, just paging seems sufficient for basic use cases.
>Additional semantics can be added later.
>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.

>> 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.
>If the server wants to provide that guarantee,
>it can mark the version as timestamped using RFC 7089 (Memento).
I think we're talking about two different things. I don't take into account 
situations when resource changes in time. For this cache control is enough 
for client to know. 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).

>> 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.
>The same way we did before.
>Hydra is there for RDF-aware representations, like JSON-LD and Turtle.
>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. There is not that much of a work needed in order to 
support it, thus we should spent some more time on that. Actually in 
previous conversations regarding Hydra design goals you agreed with me with 
these words:
"We should think of images, video, …"

>> 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.
>What aspects of paging would be necessary to detail in the API 
>documentation?
Well, it's more related to cardinality issues and iri templates. Documenting 
that given operation returns multiple or single instance of a given class is 
currently impossible without extensions. While class property cardinalities 
could be expressed with OWL restrictions on properties, expected/returned 
values doesn't give that possibility.
Also for iri templates, we don't have anything that would support auto 
generated resource Urls crafted by UI applications (from user input).

Those questions rised here are somehow related to my personal experiences 
with hydra and UI applications. I'll try to shed some more light on that 
once I advance more in my POC.

Best,

Karol

Received on Tuesday, 20 October 2015 19:45:19 UTC