Skip to content

Instantly share code, notes, and snippets.

@tpluscode
Last active March 5, 2020 14:37
Show Gist options
  • Save tpluscode/cb206598d4b3a9a7c53d844426e9e255 to your computer and use it in GitHub Desktop.
Save tpluscode/cb206598d4b3a9a7c53d844426e9e255 to your computer and use it in GitHub Desktop.

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#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" .

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
}))
<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> .
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment