RE: Clarifications and things I can not find in the Vocabulary

Thanks for your comments Thomas.. a couple of my thoughts inline.

On Tuesday, May 06, 2014 3:35 PM, Thomas Hoppe wrote:
> 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).

Cool!

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

I agree with Thomas on this. In the end, you would need to create different
Hydra API descriptions for the different versions of your API. Thus, the
version in most cases would be already somewhere in the URLs of those API
descriptions. You can of course, mark that up in Hydra by minting a custom
property. I am for the reasons Thomas stated a bit reluctant to add
something like that to Hydra itself (at least at this stage).


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

Yeah, that's definitely something I think would be quite valuable as it
would allow us to not only create more useful human-readable documentation
but also implement things like mock servers etc. I've raised ISSUE-46 for
this:

  https://github.com/HydraCG/Specifications/issues/46


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

Currently, it's not possible. At the moment you can only specify what type
of resource is returned "on success". What use cases do you have in mind? Is
it just for the creation of human-readable documentation or do you  want to
use this information somehow programmatically?


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

Exactly.


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

I'm not sure what exactly do you mean by "good practices". It is completely
up to the application on what data might be returned so it is difficult to
generalize this. But maybe I'm also simply misunderstanding you!?


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

IMO Hydra should provide enough information to start Auth* (if necessary at
all) but not specify or standardize Auth* mechanisms. The issue tracker demo
for example uses Basic Auth (required when you create a new issue). Since
that's supported by browsers out of the box and communicated via a simple
HTTP header it works as is with Hydra. It is really an orthogonal aspect.


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

Yeah, unfortunately there doesn't exist much tooling yet. I hope the
situation starts to improve as we stabilize the core vocabulary.


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

Facebook would actually be a quite interesting example as they have a
Turtle-based API. For details see here:

  http://lists.w3.org/Archives/Public/public-lod/2011Oct/0032.html


> We already discussed to model a small eCommerce/ shop API which I
> consider sensible.
> Unfortunately I'm too swamped right now to start this.

Yeah, unfortunately we all are. I'm traveling quite a lot at the moment so
I'm hardly "productive" myself. It's already hard enough to keep up with all
the mails.


> [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/#


--
Markus Lanthaler
@markuslanthaler

Received on Monday, 12 May 2014 18:52:19 UTC