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

hello markus.

On 2015-04-16 13:02 , Markus Lanthaler wrote:
> No, IMO there isn't anything specific enough in the IANA registry. I want this relation to be explicitly for Hydra clients. While content negotiation sounds nice in theory here, I think leveraging it in practice (at the level you proposed in another mail) introduces way to much complexity. Don't get me wrong, I'm not against conneg per se or for the serialization type (JSON-LD, Turtle, ...) in particular. I just don't think it makes sense to negotiate between different API description formats (RAML, Swagger, ...). They are different enough to get their own, distinct URLs. Makes sense?

no, it doesn't. hardcoding media types into link relations is an 
anti-pattern that we should avoid. it's as if HTML had <PNGimg/> and 
<GIFimg/> and <JPEGimg/> elements, and every time somebody somewhere 
came up with a new image format, there would be new links.

a link enables a client to follow that link because it wants to achieve 
a certain goal ("i'd like to GET API doc"). *what kind* of API doc it 
finds is a runtime issue. if you think you need media type hints, 
separate them from the link relation and embed them as link annotations. 
those annotations might still fail at runtime, but at least you could 
represent the fact that you think that the URI can resolve to a hydra 
representation.

and there really is no reason why you would hardcode the media type into 
the relation type. if you think all you ever want in your system is 
hydra, then simply never serve anything else and never request anything 
else, and you're set. there's still no need to hardcode this into the 
link relation. and more importantly, you shouldn't paint others into 
this particular corner, only because all you are using is hydra.

if you feel like there is no link relation that fits your current needs, 
then define and register a new one. i'll gladly help with that, either 
in a separate spec or in the hydra spec. we have a number of formats 
around that are playing in that space, so maybe it indeed is time to 
have a registered link rel for that.

that would actually play nicely with the home document format, where one 
useful link probably would be to some sort of API description. 
http://tools.ietf.org/html/draft-nottingham-json-home-03#section-4.2 
does have the capability to add media type hints, and that would be the 
way to go.

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 Thursday, 16 April 2015 22:49:24 UTC