- From: Michael Petychakis <mpetyx@epu.ntua.gr>
- Date: Tue, 6 May 2014 13:51:35 +0000
- To: Thomas Hoppe <thomas.hoppe@n-fuse.de>
- CC: "public-hydra@w3.org" <public-hydra@w3.org>
Hello Thomas, Thank you very much for the information and the references. I will have a closer study! Regards, Michael Petychakis. On May 6, 2014, at 4:35 PM, Thomas Hoppe <thomas.hoppe@n-fuse.de> wrote: > 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:52:46 UTC