Re: Specifying operations for instances

On Wed, Jun 18, 2014 at 10:51 PM, Markus Lanthaler
<markus.lanthaler@gmx.net> wrote:
> On 18 Jun 2014 at 09:53, McBennett, Pat wrote:
>> Markus Lanthaler wrote on June 15, 2014 8:09 PM:
>>> On 14 Jun 2014 at 23:27, Tomasz Pluskiewicz wrote:
>>>> I understand that the resource still supports the DELETE because it is
>>>> an instance of the ForumPost class. But in very practical terms, would
>>>> you consider the absence of the DELETE operation in the instance's
>>>> representation a good enough clue for the client not to render a
>>>> delete button?
>>>
>>> Yes, with the caveat that the ApiDocumentation doesn't tell me otherwise.
>>
>> Ok, I totally agree here, but this seems to be contradicted below at [1]...
>
> a)
>
> [...]
>
>>>> I meant the guidelines would be more appropriate than rules.
>>>>
>>>> I think what's missing is or vague is:
>>>> 1. what clients should assume if a resource representation has some
>>>> but not all of the supported operations defined by it's class
>>>
>>> The operations associated to the resource itself and the ones associated to
>>> its class are merged. After that, they are indistinguishable. Again, it doesn't
>>> matter where the operations are asserted.
>
> b)
>
>> [1]... but if this is the correct assumption, then won't the client always have to render the
>> DELETE button in the example above? There seems to be a clear inconsistency here...
>
> No. Example a) might looks like this:
>   ApiDocumentation: ForumPost supportedOperation x, y, does *not* include DELETE
>   /posts/a operation z, *not* a DELETE
>
> No DELETE in the representation of /posts/a and the ApiDocumentation also "doesn't tell me otherwise", i.e., also doesn't include a DELETE.
>
> Example b) might look like this
>   ApiDocumentation: ForumPost supportedOperation x, y, does *not* include DELETE
>   /posts/b operation x (again, *not* a DELETE)
>
> The representation of /posts/b includes some (x) but not all (y is missing) operations know to be supported by instance of the class ForumPost.
>
> Thus,
>    /posts/a has the following operations: x, y, z
>    /posts/b has the following operations: x, y
>
> Where do you see "the clear inconsistency" Pat?
>

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

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

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?

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

>
> --
> Markus Lanthaler
> @markuslanthaler
>
>
>

Received on Wednesday, 18 June 2014 21:59:54 UTC