- From: Thomas Hoppe <thomas.hoppe@n-fuse.de>
- Date: Tue, 06 May 2014 15:35:08 +0200
- To: public-hydra@w3.org
Hello Michael, let me try to answer/ comment on your questions. see below. Greets, Thomas On 05/06/2014 03:08 PM, Michael Petychakis wrote: > 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. > It is _not_ compatible with the restful architecture model to couple client and API in such a tight way that something like a version is required. Instead, the credo is to allow the clients and the API evolve independently. If you have a scenario where you can afford a tight coupling, you could just introduce an extension to hydra with a corresponding property `version` or whatever. > 1. 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. > As far as I know, the IRI template examples are known to be documented in a suboptimal manner. This is tracked here [1]. > > 1. 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. > Most likely the construct to specify responses will be removed from Hydra Core because it is also incompatible with restful ideas [2]. We thought about introducing a separate vocab to describe API documentations where it would make sense to generate documentations (much like swagger does). At runtime, however, we concluded, that it does not make sense to have it in Hydra Core. > 1. 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. > Usually I would say that this can be solved in a restful way through content negotiation, for documentation and other use-cases, I also consider this useful. This issue is known an tracked under [3]. Feel free to share your use-case. > > 1. 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. > I hope I can soon share some examples but meanwhile check the hydra console example pointed out below. > > 1. 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. > AuthN is out of scope for hydra (from my POV) as it is already solved well by existing efforts and standards like HTTP Basic Auth and OAuth. What I'm missing with these is a way to announce the possibility to authenticated with one of them. AuthZ however is also a concern of mine and I already have some Ideas about it which I will share in the future. > > 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. There is the hydra console which is a bit outdated however [4]. It can be used to browse a small issue tracker API. > 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. > We already discussed to model a small eCommerce/ shop API which I consider sensible. Unfortunately I'm too swamped right now to start this. > 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 > [1] https://github.com/HydraCG/Specifications/issues/30 [2] https://github.com/HydraCG/Specifications/issues/32 [3] https://github.com/HydraCG/Specifications/issues/22 [4] http://www.markus-lanthaler.com/hydra/console/#
Received on Tuesday, 6 May 2014 13:35:43 UTC