Clarifications and things I can not find in the Vocabulary

Hello all,

I have been trying to use hydra in practice and develop my own (python) library on top of that.
It is pretty easy and straightforward to just transform the json-ld that I create in ntriples and start from there.
But in my case, I want to be able to map it to existing web frameworks, so that people creating web APIs are able to depend on Hydra(in a similar manner they already do for swagger).

Some of the things that I miss in practice, are the following.

  1.  The API version. It should be somewhere (preferably) on the top of the ApiDocumentation, one more property that describes the api version that this description is going to be about. It is really important for migrating clients, and in order to actually have a production API.
  2.  There should be also the example property on supportedProperty or on IriTemplateMapping variable. This way a user would have an idea on how to use the corresponding property.
  3.  On operations, I am not sure if I can have an example response per statusCode. For example If I have status 200, I would like to return a specific response, while on a different status a different response. Those responses could be different documents (since they vary and sometimes can be lengthy), in a similar manner like RAML does. They could be referenceable  over http, in order to be more compatible with the json-ld(rdf) philosophy.
  4.  For those responses, it would be also important to have a serialisation parameter, because for some reposes it would make sense to return json, in some others xml or even turtle.
  5.  Insisting on responses, since those responses ultimately could be other json-ld documents based on vocabularies, it would be nice to have examples on that for good practices.
  6.  I have already asked and I know it is a bit early(others I think have the same questions, so I am not going to insist) regarding the authentication and authorisation, I think we should start the discussion at least in which level this would be addressed. For example, could I have a different A&A mechanism per supportedClass? I think it makes sense. We could even start building some first notions about this component based on http://www.w3.org/wiki/WebAccessControl and http://www.w3.org/wiki/WebID. They are already quite mature, and I do not think it would affect the overall scope of the Hydra vocabulary, on the contrary it would even boost the conversation by trying to apply it on specific scenarios. Of course, raml and swagger have already an approach that is really stable and deals with the state of the art A&A in production level, that could be adopted in the present vocabulary.

At some points I may be totally wrong but those are the thoughts that I have working with Hydra and try to apply it on existing APIs. In fact, i would like to see tools similar to swagger, raml and api-blueprints starting existing for hydra also. In any case, I could use more complete examples on Hydra in order to better understand how some stuff are intended to be used.
I would propose we could even start with a mature API(like facebook, twitter etc) and start writing its Hydra documentation. This way, anyone(including me) could easier comprehend all the parameters of the vocabulary.

Kind regards,

Michael Petychakis
Electrical & Computer Engineer, Dipl Eng, Research Associate
Decision Support Systems Laboratory
School of Electrical and Computer Engineering
National Technical University of Athens

9 Heroon Polytechneiou Str
Zografou - Attica, 15773, Hellas
Tel:  +30 210 7723555
Fax: +30 210 7723550