- From: Markus Lanthaler <markus.lanthaler@gmx.net>
- Date: Thu, 19 Jun 2014 00:27:58 +0200
- To: <public-hydra@w3.org>
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 @markuslanthaler
Received on Wednesday, 18 June 2014 22:28:29 UTC