Re: What is the correct media-type for a Hydra specification?

> On Apr 14, 2015, at 2:30 AM, John Walker <john.walker@semaku.com> wrote:
> 
> Hi Jonathan,
>  
> Maybe check out this section of the spec:
> http://www.hydra-cg.com/spec/latest/core/#discovering-a-hydra-powered-web-api
>  
> So you could use an HTTP Link header to point to a resource that would be a Hydra document.
>  
> As the rdfs:range of hydra:apiDocumentation property is the hydra:ApiDocumentation class, you can entail that anything linked to with this relation is a Hydra document.
>  
> You could also use the same hydra:apiDocumentation property in some JSON to link out to a list of documents.
>  
> {
>   "@context": {
>     "hydra": "http://www.w3.org/ns/hydra/core#",
>     "hydra:apiDocumentation": {
>       "@type": "@id"
>     }
>   },
>   "hydra:apiDocumentation": [
>     "doc1",
>     "doc2",
>     "doc3"
>   ]
> }

IMO , the way to know you’re accessing Hydra Documentation is to look for something of type hydra:ApiDocumentation. Note that this is not necessarily a JSON-LD document unless you explicitly request that format; I might well provision a Hydra API and support text/turtle as a mime type, both for the documentation and the interface itself. Of course, most would probably use another serialization such as JSON-LD, and saying Accept: application/ld+json is the way to signal that.

Use the Link header to find the documentation endpoint, and then request it, also with application/ld+json. You can then look for hydra:ApiDocumentation, although that could concievably require compacting the document with a context your application is prepared with.

You could also look for hydra:apiDocumentation, and infer that it’s value is of type hydra:ApiDocumentation, but the hydra:apiDocumentation may just be used in a Link Relation with type "http://www.w3.org/ns/hydra/core#apiDocumentation”. Note that hydra:apiDocumentation may never actually appear in a document.

Gregg

> HTH
>  
> John
> 
> > On April 14, 2015 at 11:03 AM "Robie, Jonathan" <jonathan.robie@emc.com> wrote:
> > 
> > 
> > I think several people are saying I should (1) read the document using application/json+ld, then (2) identify the document as a Hydra document when I see this:
> > 
> > { 
> > "@context": {
> > ...
> > "hydra": "http://www.w3.org/ns/hydra/core#",
> > "hydra:property": {"@type": "@vocab"}
> > },
> > 
> > The problem I have with this in my context is that I want to tell someone what kinds of descriptions are available before they have an instance of the document. In the REST world, the mechanism I have for doing that is the media type. I don't want to fetch the document first and look at it to see if it is a Hydra description.
> > 
> > Ironically, the reason I want to do this is that I agree with much of what has been said here, I want to get out of the business of creating custom serializations for media types and use Hydra as a generic hypermedia serialization format. 
> > 
> > Jonathan
> > ________________________________________
> > From: Tomasz Pluskiewicz [tomasz@t-code.pl]
> > Sent: Tuesday, April 14, 2015 12:43 PM
> > To: Erik Wilde; Robie, Jonathan; Nandana Mihindukulasooriya; public-hydra@w3.org
> > Subject: Re: What is the correct media-type for a Hydra specification?
> > 
> > Hi
> > 
> > I'd like to disagree. I've never really understood the notion of media types in the context of RDF data. At least not for specific vocabularies. You already do have them defined for RDF serializations eg. application/rdf+xml, text/turtle or application/ld+json. Would you now start adding hydra profiles to each of the serialization-specific media types? I don't think so.
> > 
> > It has been rightly pointed out that RDF (Linked Data) world does not need media types, because the semantics are inherently defined by the data itself through relations and rdf types. And so hydra API can be negotiated so that they return Turtle, RDF/XML, JSON-LD or anything else depending on the client's capabilities/preferences while still retaining the full semantic description of the data.
> > 
> > This IMO is a great benefit over traditional RESTful APIs, which usually stick to a single serialization format (JSON nowadays) or otherwise must define the hypermedia controls separately for each supported serialization. RDF is superior through separation of the two concerns: syntax and semantics.
> > 
> > Regards,
> > Tom
> > 
> > April 14 2015 8:55 AM, "Erik Wilde" <dret@berkeley.edu> wrote:
> > > hello jonathan.
> > >
> > > On 2015-04-13 23:47, Robie, Jonathan wrote:
> > >
> > >> A profile would be perfect. And yes, I think that should be added.
> > >
> > > it actually would be very cool to see this happening. i guess
> > > http://www.w3.org/ns/hydra/core or http://www.w3.org/ns/hydra/core#
> > > would be good candidates. i personally dislike the URIs with empty
> > > fragments, but that's just a matter of taste. either way, the spec
> > > probably should explicitly say what the profile URI is, so that this
> > > would be clear without guessing.
> > >
> > > cheers,
> > >
> > > dret.
> > >
> > > --
> > > erik wilde | mailto:dret@berkeley.edu - tel:+1-510-2061079 |
> > > | UC Berkeley - School of Information (ISchool) |
> > > | http://dret.net/netdret http://twitter.com/dret |
> > 
> >

Received on Tuesday, 14 April 2015 18:45:12 UTC