README.md

Intro

This document presents some possible ideas for how a server request might get matched to the Hydra's API Documentation.

All turtle snippets ignore prefixes and base URI for bervity and only show the relevant subgraph. All requests assume Content-Type: text/turtle

api.ttl

<api#Post> 
  a hydra:Class ;
  hydra:supportedOperation <api#post-get>, <api#post-put> .
  hydra:supportedProperty [
  	hydra:property <api#comments>
  ] .
   
<api#post-get>
  a hydra:SupportedOperation ;
  hydra:method "GET" .
   
<api#post-put>
  a hydra:SupportedOperation ;
  hydra:method "PUT" ;
  hydra:expects <api#Post> .
	  
<api#comments>
  a hydra:Link ;
  hydra:supportedOperation <api#comment-post>.
   
<api#comment-post>
  a hydra:SupportedOperation ;
  hydra:method "POST" ;
  hydra:expects <api#Comment> .
   
<api#comment-delete>
  a hydra:SupportedOperation ;
  hydra:method "DELETE" .
  
<api#Comment> 
  a hydra:Class ;
  hydra:supportedOperation <comment#put> .
    
<api#my-comments> 
  a hydra:Link ;
  hydra:supportedOperation <api#my-comment-delete> .
  
<api#my-comment-delete>
  a hydra:SupportedOperation ;
  hydra:method "DELETE" .

examples.md

Successful requests

Match supported operaton of instance type

GET /post/easy-hydra

Will call <api#post-get> because it is directly supported by the <api#Post> class.

Match by SupportedProperty -> supportedOperation

POST /post/easy-hydra/comments

<> schema:title "Now you convinced me to RDF" .

Will call <api#comment-post> because it is supported by the <api#comments> property and/post/easy-hydra/comments resource is an object of that relation.

Match by payload type

PUT /post/easy-hydra

<api/post/easy-hydra> a <Post> .

Even though the requested resource does not exist, I expect it would call <api#post-put> based on the method and requested representation.

Failed requests

Sending the wrong rdf:type

PUT /post/easy-hydra/comment/1

<> a <Post> .

Trying to replace the representation of a comment with a post? Nope. Although a PUT request would be allowed by the <post/easy-hydra/comment/1> resource, the payload type does not match.

No operation

DELETE /post/easy-hydra/comments

This one is quite obvious. No such operation on this resource at all. Status 405

Undecided

Ambiguous

DELETE /post/easy-hydra/comment/1

The resource supports this operation both by its class as well as the <api#my-comments> property. 🤷

Status 500 unless selected by custom code?

Implicit

GET /me

I propose to have an API-wide option to implcitly return the representation of any resource on a GET resource, even if it does not have a SupportedOperation.

Might be set up as an optional handler?

import * as hydra from 'hydra-box'

// the usual, to load representation and find operations
app.use(hydra.middleware()

// fall back to this one which will simply pass on req.hydra.resource.dataset
app.use(hydra.implicitRepresentation({
  // possibly with some options to fine-tune this behavior
}))

resources.ttl

<post/easy-hydra> 
  a <Post> .

<post/easy-hydra> <api#comments> <post/easy-hydra/comments> .

<post/easy-hydra/comments> 
  a hydra:Collection ;
  hydra:member <api/post/easy-hydra/comment/1> .
		
<post/easy-hydra/comment/1> a <Comment> .

<me> <api#my-comments> <post/easy-hydra/comment/1> .