RE: Looking for help and feedback

Hi John,

On 3 Sep 2014 at 19:26, John Walker wrote:
> 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.

Aweseome!


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

Good to hear


> Essentially what I understood is that Hydra defines a (meta)model that I
> can use to model my API.

Yeah. It basically describes what classes a consumer of an API should understand, constraints on those classes and operations on instances of those classes (as well as on targets of link properties).


> Unfortunately I based myself on the draft spec, so I've not used the new
> proposed collection design.

Since you minted your own properties, there's no problem with using hydra:Collections the way you do. The new design simply allows them to be used also with properties that have a range different than hydra:Collection.


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

Yeah, do you see any problem with the above?


> 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> ;

Shouldn't

>   hydra:collection <doc/concepts/1/narrower> .

Be asserted on id/concepts/1 instead of doc/concepts/1? At least you do that in the first example.


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

Yes, the rest looks good. It is a bit difficult though to understand where the document boundaries are. The hydra:manages assertion should be in the same document as the hydra:collection statement. Otherwise a client wouldn't know why it should follow that link.



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

If a separate resource makes sense, then yeah, definitely. It makes the interactions much simpler. In this case I'm not sure it makes much sense though.


> Or have the client PUT a new collection minus that statement (probably
> won't scale well)?

If you have a separate resource type, you can simply define a POST operation which expects that type.


> Are there other options worth considering link HTTP LINK/UNLINK methods?

In cases like this, I would use LINK and UNLINK. This is exactly what they have been created for.


HTH,
Markus


--
Markus Lanthaler
@markuslanthaler

Received on Sunday, 7 September 2014 20:47:25 UTC