Looking for help and feedback

Hi All,
 
A couple of weeks back I decided to have a go at writing some API documentation
using Hydra primarily as a learning-by-doing exercise.
 
I started with a blank slate and settled on describing an API for managing SKOS
thesauri.
This kind of ties into a prototype implementation I'm working on hopefully the
two will come together at some point.
Maybe also could serve as a reference for others.
 
I have not made anywhere near as much progress as I'd like, paying work takes
priority :)
 
Anyway I decided to share the work in progress on this list for comment and
feedback:
https://github.com/jaw111/skos-api
 
To be honest I found it took a good while to get my head around Hydra, but
things are slowly making sense.
Essentially what I understood is that Hydra defines a (meta)model that I can use
to model my API.
 
Unfortunately I based myself on the draft spec, so I've not used the new
proposed collection design.
 
I have to say that a point for confusion is how to deal with information
resources vs. non-information resources.
I'm half-tempted to sidestep the issue and not bother to make the distinction,
but feel that is taking the easy way out.
Note I don't want to get into any re-discussion of httpRange14, hash v slash and
all that stuff.

I've used slash pattern in the examples here and assume the relevant redirects
are in place, but hash pattern would serve equally well.
 
Imagine I have a representation of a concept, I'd expect the Turtle
representation to be something like:
 
<doc/concepts/1> a foaf:Document ;
  foaf:primaryTopic <id/concepts/1> ;
  dct:created "2014-08-08T00:00:00Z"^^xsd:dateTime ;
  dct:modified "2014-09-03T00:00:00Z"^^xsd:dateTime ;
  dct:creator <id/users/7> .
 
<id/concepts/1> a skos:Concept ;
  skos:prefLabel "Classical music" ;
  skos:topConceptOf <id/conceptSchemes/1> ;
  skos:narrower <id/conceptSchemes/2> , <id/conceptSchemes/3>,
<id/conceptSchemes/4> .

That all seems pretty simple and would be pretty easy to make into a nice
JSON-LD representation too.

Imagine that I now want to split out my list of narrower concepts into a
separate hydra:Collection resource, how would one go about linking to that
collection resource?

My (maybe naive) approach would be to modify the representation to:

<doc/concepts/1> a foaf:Document ;
  foaf:primaryTopic <id/concepts/1> ;
  dct:created "2014-08-08T00:00:00Z"^^xsd:dateTime ;
  dct:modified "2014-09-03T00:00:00Z"^^xsd:dateTime ;
  dct:creator <id/users/7> ;
  hydra:collection <doc/concepts/1/narrower> .

<doc/concepts/1/narrower> a hydra:Collection ;
    hydra:manages [
        hydra:property skos:narrower ;
        hydra:subject <id/concepts/1> .
    ] .
 
<id/concepts/1> a skos:Concept ;
  skos:prefLabel "Classical music" ;
  skos:topConceptOf <id/conceptSchemes/1> .

Then when dereferencing the collection, the representation would be:

<doc/concepts/1/narrower> a hydra:Collection ;
    hydra:manages [
        hydra:property skos:narrower ;
        hydra:subject <id/concepts/1> .
    ] .
 
<id/concepts/1> skos:narrower <id/conceptSchemes/2> , <id/conceptSchemes/3>,
<id/conceptSchemes/4> .

Does this seem reasonable.

I'm also wondering how one could best go about deleting an individual statement
such as "<id/concepts/1> skos:narrower <id/conceptSchemes/2>".
Would it be a best practice to have this as a separate resource that can be
DELETEd, if so how to link to that resource?
Or have the client PUT a new collection minus that statement (probably won't
scale well)?
Are there other options worth considering link HTTP LINK/UNLINK methods?

Ideas/feedback welcome!

Cheers,
John

Received on Wednesday, 3 September 2014 17:27:11 UTC