Hydra relative

readme.md

Proposal for how to describe resources with Hydra to achieve search functionality using relative URL templates

The API Documentation describes a :UserCollection class, which supports a search property :searchUsers to have the collection filtered by constructing a URL Template <api/user-search-template>. The template has a URL identifier to allow sharing it between the API Documentation and actual resources to filter.

Given the two example instances of the collection, the client would be able to construct URLs relative to the subject of :searchUsers predicate like:

/users?first=John

/users/unverified?age=20

The <api/user-search-template> hydra:resolveRelativeTo hydra:LinkContext triple is crucal enabler of that functionality

api.ttl

<api> 
  a hydra:ApiDocumentation ;
  hydra:supportedClass :UserCollection ;
.

:UserCollection
  a hydra:Class ;
  hydra:supportedProperty [
    hydra:property :searchUsers ;
  ] ;
.

:searchUsers
  rdfs:subPropertyOf hydra:search ;
  hydra:supportedOperation [
    hydrabox:variables <api/user-search-template> ;
    hydra:method "GET" ;
  ] ;
.
    
<api/user-search-template>
  a hydra:IriTemplate ;
  hydra:template "{?first,last,age}" ;
  hydra:resolveRelativeTo hydra:LinkContext ;
  hydra:mapping [
    hydra:variable "first" ;
    hydra:property schema:givenName ; 
  ] , [
    hydra:variable "last" ;
    hydra:property schema:familyName ; 
  ] , [
    hydra:variable "age" ;
    hydra:property schema:age ; 
  ]
.

unverified-users.ttl

<users/unverified>
  a :UserCollection ;
  :searchUsers <api/user-search-template> ;
  hydra:manages [
    hydra:property rdf:type ; 
    hydra:object :User ;
  ] , [
    hydra:property :verified ; 
    hydra:object false ;
  ]
.

users.ttl

<users>
  a :UserCollection ;
  :searchUsers <api/user-search-template> ;
  hydra:manages [
    hydra:property rdf:type ; 
    hydra:object :User ;
  ] , [
    hydra:property :verified ; 
    hydra:object true ;
  ]
.