W3C home > Mailing lists > Public > public-hydra@w3.org > June 2014

RE: Specifying operations for instances

From: Markus Lanthaler <markus.lanthaler@gmx.net>
Date: Thu, 19 Jun 2014 00:27:58 +0200
To: <public-hydra@w3.org>
Message-ID: <019201cf8b44$902c40d0$b084c270$@gmx.net>
On 18 Jun 2014 at 23:58, Tomasz Pluskiewicz wrote:
> The ApiDocumentation is described as similar to the documentation
> developers would currently manually produce in natural language and as
> such I assumed it wouldn't change unless the contract changed. Much like

Well, if the ApiDocumentation changes, the "contract" changes.

> traditional documentation wouldn't. That's the root of my confusion.
> With that assumption in mind I couldn't understand how the client could
> decide that some of the operations are actually "not available".

Because the ApiDocumentation is *not* hardcoded into the client. It is interpreted at runtime. With the traditional, natural-language documentation that's impossible. 

> The idea of adjusting the ApiDocumentation representation sounds
> interesting but a little bit awkward. Again, traditional documentation
> wouldn't change so that developers can learn the API from written
> text. Being in a machine-readible format is great but documentation is
> still documentation. And ApiDocumentation is something else...

Is it? Just because it's up to date? Also with current services you might get a different documentation if you log in as a "premium partner".

> Also some operations are valid for a resource in a specific state.
> Such operations will never be returned in the representation of
> ApiDocumentation. Would it mean they are not supported?

I thought we discussed this already!? 

> Come think of it now I would probably have modelled this part of Hydra
> differently so that the assumption about ApiDocumentation is that it
> contains all possible operations the API defines. These operations would
> have been identified resources so that they can be dereferenced. And
> then instances could reference them by URI or add their own additional
> operations.

That approach is fully supported by the current design.

> However in such model all operations would have to be
> decalred or referenced in the resource's representation.
> ApiDocumentation would be just that - documentation. One from which a
> developer can get a bigger picture and a centralized repository of API
> metadata.

That's the difference. The ApiDocumentation is not really intended for the developer. It is for the client. The last thing that I as a developer want to do is to read documentation. If a machine can do it for me, let the machine do it. There are much more important and interesting things for me to do.

Markus Lanthaler
Received on Wednesday, 18 June 2014 22:28:29 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 15:53:59 UTC