Re: Pagination (ISSUE-42)

Gregg Kellogg
> On 2015-02-03 16:31, Ruben Verborgh wrote:
>> Hi Andrew,
>> 
>>> In my api's and clients I much prefer to use offset and limit as a more fundamental concept to partial collections.
>> 
>> This has strong repercussions of the cacheability of answers,
>> which is crucial when many clients consume the API.
>> (Graphs: http://linkeddatafragments.org/publications/iswc2014.pdf)
>> 
> 
> I've also disliked limit/offset endpoints because they empower users to query for very large portions of data unless the limit parameter is constrained.

IMO, using limit/offset is natural, and expressing them as URI query parameters creates resource identifiers useful for first/last/previous/next links. In my implementations, the first page of the collection typically has no limit/offset parameters, but the rest do.

>>> Offset and limit is also how SQL databases tend to handle these things
>> 
>> But we shouldn't make any assumptions on the underlying datasource.
>> 
>> I'm not against limit/offset per se, but we definitely first support a more simple interface.
> >
> 
> But what is there to support in terms of limit/offset, really? I mean it is already possible to define a templated link and make the limit and offset as variables. So it is possible to define a templated link to nth page. And indeed dynamically calculated pages are likely to use limit and offset underneath anyway. Also, on the other hand limit and offset can easily be used with the proposed firstPage, nextPage etc, assuming some predefined page size.
> 
> {
> "@id": "/collection?limit=10&offset=10",
> "@type": "Page",
> "pageOf: {
> "@id": "/collection",
> "nextPage": "/collection?limit=10&offset=20",
> "previousPage": "/collection?limit=10",
> "search": {
> "template": "/collection{?limit,offset}"
> }
> }
> }
> 
> Bottom line is we may want to define property to replace hydra:search bove. All the other building blocks are in place and how we address our pages is irrelevant IMO.

Again, IMO, separate Page and Collection types is probably going too far, and the entire collection can be viewed as a single resource, which is "paginated" using limit/offset. Each Collection resource provides first/last/previous/next links, as well as itemsPerPage/totalItems. itemsPerPage (or other similarly named resource) can be taken as a contract on limit, and requests where limit != itemsPerPage and offset mod limit is not zero could return an application error; this would address cachability concerns, but it's entirely up to the service to control this, as it should be.

We also don't need to mandate what query parameters are used, and could simply be "?page="; why should a client care? It's entirely determined by the collection metadata.

Semantically, a single Collection type with size and paging information is adequate for our needs, in spite of the semantic slipperiness of distinguishing a full Collection from individual paged components. In any case, from a model perspective, it's not really a resource at all, but a way of expressing entity relationships that are too big (potentially) to be serialized on the subject or object entity representations.

Gregg

>> Best,
>> 
>> Ruben
>> 
> 
>

Received on Tuesday, 3 February 2015 17:58:49 UTC