RE: Explicit description of paging in hydra:IriTemplate to enable random access to hydra:PagedCollection

On 16 Jun 2014 at 15:42, Jindřich Mynarz wrote:
> should paging properties (e.g., page or limit and offset) be
> explicitly described in a hydra:IriTemplate that returns a
> hydra:PagedCollection or is it sufficient to embed them in paging
> links (e.g., hydra:nextPage, hydra:previousPage) contained in
> representations of hydra:PagedCollection?

Generally speaking, I would say they should simply be embedded in paging as that reduces coupling.


> If paging properties are
> explicitly described, then it may allow clients to do random access of
> the hydra:PagedCollection.

In some cases, perhaps. But it quickly becomes quite complex. IMO most use cases are better addressed by filtering the collection to get to the desired data. Do you have an example where that doesn't work? "Jump to third page" doesn't count :-P


> For example, an API may provide a hydra:IriTemplate described in the
> following manner:
> 
> :simple-search-person-template a hydra:IriTemplate ;
>   hydra:template "/person{?name}" ;
>   hydra:mapping [
>       a hydra:IriTemplateMapping ;
>       hydra:variable "name" ;
>       hydra:property schema:name ;
>       hydra:required true
>     ] .
>
> The API can then provide results of dereferencing the completed
> hydra:IriTemplate as hydra:PagedCollection with hydra:Links to other
> pages of the resulting collection:
> 
> </person?name=foo> a hydra:PagedCollection ;
>   hydra:nextPage </person?name=foo&page=2> .
>
> Or instead, the paging properties may be directly factored into
> hydra:IriTemplateMappings. However, in this case it's not clear what
> properties should the paging be mapped to.

In fact, in most cases it is not clear IMO. Also, I would generally recommend to use something more stable offsets than page=2 as otherwise you might miss several items if the collection changes while you traverse it.


> :simple-search-person-template a hydra:IriTemplate ;
>   hydra:template "/person{?name,page}" ;
>   hydra:mapping [
>       a hydra:IriTemplateMapping ; hydra:variable "name" ;
>       hydra:property schema:name ; hydra:required true ], [ a
>       hydra:IriTemplateMapping ; hydra:variable "page" ; hydra:require
>       false
>     ] .
>
> Is this an anti-pattern? Is there a better way how to enable random
> access of a hydra:PagedCollection?

Let's see if we find a compelling use case where random access makes sense (in this case it doesn't IMHO) and discuss it then. In this case here, there's no indication of what subset of the data would be found on page 2 for example. So why would a client want to jump directly there then?


--
Markus Lanthaler
@markuslanthaler

Received on Wednesday, 18 June 2014 11:45:55 UTC