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

hello markus.

On 2015-04-18 04:06, Markus Lanthaler wrote:
> On 17 Apr 2015 at 00:48, Erik Wilde wrote:
>> 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)

i always get tripped ub by the semweb community's special use of media 
types, so i should have been more specific. when i say "media type" i am 
talking about one that meaningfully exposes the represented data, not 
just the metamodel it is represented in. so it should be something where 
hydra, hydra++, or non-RDF API decription media types can be 
meaningfully labeled. the link relation type should not make any 
assumptions about the model type (i.e., hydra or something else) that's 
linked to.

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

sure. if you want to implement it that way, why not. you could also have 
different URIs, if you prefer, but most importantly, you would not have 
link relations for all those media types.

i'd have link relations saying "here's human-readable documentation", 
and then media types that at runtime would determine how the 
documentation is represented. that way, you don't need HTMLdocumentation 
and plaindocumentation and ODFdocumentation and WordDocumentation link 
relation. that's something that would be bad practice.

come to think of it, maybe we should whip up an I-D for these two 
relations: human-readable and machine-readable documentation. both 
aren't yet registered, and would be nice to have in many APIs. and i 
would strongly advocate for making those media-type independent.

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

but so are all image formats, they are very different in all respects, 
and yet we all link to them as being images, and what matters that one 
link relation may say "find a thumbnail version over here", and another 
one says "find the full-size version over here".

imagine the proliferation if every link-rel/media-type permutation had 
its own link relation type. and as i pointed out in my previous email, 
you are gaining absolutely nothing by doing this. separation of concerns 
is a good things, and this is a textbook place to do it.

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

media types hints on links are just suggestions, because it does not 
make any sense to assume that only because the link says there's some 
media type to be expected, the server will behave like this forever. and 
very often, i think they are not needed, but it seems that some people 
like them. i wouldn't necessarily recommend to use them, i just 
mentioned them in case you though there was something to be gained to 
associated this kind of information with the link (there usually isn't).

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

well, i actually like the idea of having one, because it seems this 
space is active, and it would be good to have one. but then it should be 
reusable by everybody developing their own models.

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

that's a bit narrow as perspective. imagine that API description gain 
traction. it would be much better for API desc/doc crawlers if they 
could follow a well-known link relation, instead of everybody cooking up 
their own way how their specific model has to be linked.

and honestly, it's hard for me to imagine what would be hard for people 
to understand if you told them: "use the 'api-doc' link relation type 
when linking to hydra resources." what would be the problem?

cheerio,

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 Saturday, 18 April 2015 23:05:14 UTC