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

Hi,

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? If paging properties are
explicitly described, then it may allow clients to do random access of
the hydra:PagedCollection.

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.

: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?

- Jindřich

-- 
Jindřich Mynarz
http://mynarz.net/#jindrich

Received on Monday, 16 June 2014 13:42:55 UTC