- From: Tomasz Pluskiewicz <tomasz@t-code.pl>
- Date: Wed, 18 Jun 2014 23:58:30 +0200
- To: Markus Lanthaler <markus.lanthaler@gmx.net>
- Cc: public-hydra@w3.org, "McBennett, Pat" <McBennettP@dnb.com>
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