RE: Specifying operations for instances

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