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

On 17 Apr 2015 at 00:48, Erik Wilde wrote:
> 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.

I thought I was clear about this but apparently not clear enough. I'm *not* advocating to hardcode the media type in the link relation. It is completely fine to use conneg to negotiate between, e.g., JSON-LD and Turtle (as I explained above)


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

Would you also advocate to use conneg to negotiate between HTML, plain text, OpenDocument, Microsoft Word, ...?


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

To a certain degree. Nothing prevents other API documentation formats to use the same link relation in the future. At the moment, Hydra is different enough to *every* other API document out there to get a separate link relation. It is based on a different data model and a completely different processing model than anything else out there (to the best of my knowledge).


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

That introduces a much tighter coupling than a more specific link relation type IMO. Say we did that when JSON-LD wasn't standardized yet. We would have needed to update every single link in that case.


> and there really is no reason why you would hardcode the media type into
> the relation type.

Fully agreed and if you read again what I wrote you'll see that I never suggested that.


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

No one is obliged to use JSON-LD + Hydra. Those who want to use it, need to follow the spec, the others couldn't care less about it. I want to make the lives of those that want to use it as simple as possible.


> if you feel like there is no link relation that fits your current needs,
> then define and register a new one.

No need to register it. We can use a URL that derefences to its definition. That's what we did here. We did the same with JSON-LD contexts [1] (after consultation with the designated link relation experts).


Cheers,
Markus


[1] http://www.w3.org/TR/json-ld/#interpreting-json-as-json-ld


--
Markus Lanthaler
@markuslanthaler

Received on Saturday, 18 April 2015 11:06:41 UTC