Re: Hydra Design Goals: How important is RDF?

Am 05.10.2015 11:44 schrieb Asbjørn Ulsberg <asbjorn@ulsberg.no>:
>
> 2015-10-03 1:44 GMT+02:00 Melvin Carvalho <melvincarvalho@gmail.com>: 
>

>
> For many people, I expect Hydra to 
> "just" be an alternative to HAL[1], Siren[2], API Blueprint[3], 
> Swagger[4], Slate[5], etc. The fact that it is powered by RDF will be 
> a (very) nice bonus, but probably not something that will be the huge 
> sell. For many, I expect the RDF part of it is something that will be 
> discovered long after Hydra has been chosen as the format in which to 
> describe their HTTP APIs. 

I would like to make it a point that Hydra is very different from the above mechanisms in that is not a tool to describe a vendor-specific API and its vendor-specific types. Rather, its real potential is to describe APIs in such a way that, given a common vocabulary, a generic Hydra client can understand the attribute semantics and interact with the resources without having to be implemented specifically for an API. Schema.org happens to be just such a common vocabulary which covers things of interest on the Web. 

>
> > Whats the value add, compared with just documenting APIs in the 
> > old fashioned way? 
>
> What I experience most people having issues with when coming from 
> HTTP/REST alternatives like SOAP, is the lack of a service description 
> (WSDL) from which they can get an auto-generated and statically typed 
> client from. While hypermedia does not fit great with static typing, 
> having a service description that a client can be automatically 
> created from, is extremely valuable. A default Hydra to AngularJS[6] 
> or Aurelia[7] interface generator would not only not be unthinkable, 
> but extremely powerful. 

Opinionated as I am, I would call this the WADL fallacy. Generating API clients is as if we would have to generate clients in order to access Web pages. This is not how the Web works. In APIs we should do what the browser does, or what an Atom client does: it understands the semantics of the responses because the media type carries the semantics in itself. Hence you can visit web pages and subscribe to feeds *without* reading an API description or generate a client first.

Json-ld in that regard is the media type that carries commonly agreed semantics, defined in public vocabularies like Schema.org and Hydra.

I think it would help a lot if we would build Hydra so that it enables such a generic client, maybe use such a client as proof of concept. I plan to look into this in the next weeks, is anyone interested and has some time left? 

>
> A service description is also a great basis for auto-generated 
> documentation. It's not hard to envision a default Hydra to Slate, API 
> Blueprint or Swagger converter, for instance. 

Nothing against that, it helps adoption. We would be catering to the old-fashioned ways of vendor-specific API descriptions, but hey, that is how the API industry works today. 

My 2 cents. 

Best, 
Dietrich