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

I'm asking this context in the context of RADL (RESTful API Description Language). RADL documents the media types that are used in an API, and I wanted to distinguish Hydra from LD-JSON with a separate media type entry in the RADL description.  If there is no specific media type, I should simply document that I'm using the ld-json media type for Hydra documents, but it feels like a specific media type would be helpful.

Jonathan


________________________________
From: Nandana Mihindukulasooriya [nmihindu@fi.upm.es]
Sent: Tuesday, April 14, 2015 12:00 PM
To: public-hydra@w3.org
Cc: Robie, Jonathan
Subject: Re: What is the correct media-type for a Hydra specification?

Hi,

I was just wondering, what are additional benefits of having a specific media type in this case?

Is it to make the semantics more explicit? If I understand correct, currently, the triple "<http://.../myApi> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/ns/hydra/core#ApiDocumentation> . " in the content of the documentation serves for that purpose. Are there advantages expressing that using a media type [ instead of / in addition to] the semantics expressed in the content?

One hypothetical scenario I could think of is that if Hydra evolved to have two versions and if an API supports both versions, a client can request the version that it prefers using the content negotiation.

GET /hydra/doc
Accept: application/vnd.ex.hydra.v2.ld+json

But the same thing can be done with alternative ways too, for example, having a different relations in the Link header in the discovery phase for different versions.

To answer your question, as far as I know (as a newbie), there is no specific media type defined for hydra api documentation. 'application/ld+json' and the content says it is an ApiDocumentation using rdf:type. But I would be interested to know where you are coming from?

Best Regards,
Nandana


On Tue, Apr 14, 2015 at 7:48 AM, Thomas Hoppe <thomas.hoppe@n-fuse.de<mailto:thomas.hoppe@n-fuse.de>> wrote:
Hi,
what do you mean by 'correct media-type for a hydra specification'?
Hydra is a vocabulary to describe Web APIs, so I assume you are talking
about a Web API which is described in terms of hydra.
In that case, there is no such thing as a default.
REST APIs (and its clients) are supposed to stick to the content negotiation mechanism [1]
which is used to identify a suitable media type for either party.
Greets, Thomas

[1] http://en.wikipedia.org/wiki/Content_negotiation

On 04/14/2015 07:40 AM, Robie, Jonathan wrote:
What is the correct media-type for a Hydra specification?  Is there a media type more specific than application/ld+json?

Jonathan