RE: Specifying operations for instances

> -----Original Message-----
> From: Markus Lanthaler [mailto:markus.lanthaler@gmx.net]
> Sent: Monday, July 07, 2014 5:03 PM
> To: public-hydra@w3.org
> Subject: RE: Specifying operations for instances
> 
> On 3 Jul 2014 at 23:40, McBennett, Pat wrote:
> > Markus Lanthaler wrote on June 18, 2014 9:51 PM:
> >> Example a) might look 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?
> >
> > (Sorry for the delay in replying - work and travel getting in the
> > way!)  So yes, I still see an inconsistency. Let me try to illustrate reusing
> your examples.
> >
> > From the original a) above '...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?'
> > - Markus: 'Yes...'
> 
> The "..." is very important here as I said [1]
> 
>   "Yes, with the caveat that the ApiDocumentation doesn't tell me
> otherwise."
> 
> 
> > So I interpreted Tomasz's original description as saying that the following
> scenario existed:
> >
> > c)
> > ApiDocumentation: ForumPost supportedOperation x, y, *does* include
> > DELETE /posts/a operation z, *not* a DELETE
> 
> This scenario of course exists but it means that the server clearly tells the
> client that /posts/a *supports* the DELETE operation.
> 
> 
> > ...in which case Tomasz's UI would probably render a DELETE button for
> > '/posts/a' (since the DELETE operation *is* present in the API
> > documentation), *but* that button would be grayed out and disabled
> > (since the DELETE operation *is not* present in the instance's
> representation). That's what I was agreeing with, and I thought you were
> saying 'Yes' to too.
> 
> Nope. There's no reason to gray it out and disable that button. If that would
> be the case, then associating operations to classes in an ApiDocumentation
> would be completely useless as you would have to repeat exactly the same
> representation in each "instance representation".
> 

Ok, but what exactly is the "instance representation" telling me then? I can only assume that it's telling me about 'extra' or 'new' operations that it supports, but that were never mentioned in the API documentation - is that correct...?

> 
> > But in b), you then stated that the '...the operations associated to
> > the resource itself and the ones associated to its class are merged.
> > After that, they are indistinguishable', which seemed to imply that we
> > must always 'merge' the operations from the API documentation and the
> resource instance, which from my c) above would mean:
> >
> > /posts/a operation z, x, y, DELETE (i.e. I must 'merge' all operations
> > from the API doc and the resource instance.)
> 
> That's right and the whole idea behind it.
> 

Ok, so again, then I assume there is never a need for an "instance representation" to state explicitly that it supports an operation if that operation has already been stated as being supported in the API documentation for the class of this "instance".

> 
> > And therefore Tomasz's UI should now render the DELETE button as
> > *enabled* (as well as enabling operations for z, x and y of course,
> 
> Right
> 
> 
> > when in fact the only operation '/posts/a' actually supports right now is 'z').
> 
> If that's the case, then the ApiDocumentation is lying in the sense that it is
> asserting false facts and should be fixed.
> 
> 
> > I'm pretty sure that wasn't your intended meaning. I think you
> > probably meant 'additional operations appearing in the resource
> > instance at runtime should be included (or considered
> > 'enabled') by the client, even if they never appeared in the API
> > documentation, whereas operations declared in the API documentation,
> > but missing from the resource instance can be considered 'Unavailable
> > (or 'disabled') at this time''. But anyway that's where I was seeing the
> inconsistency.
> 
> Nope, that was not was I meant and I hope this email clarifies this. What
> value would an operation declared in the API documentation have if it would
> have to be declared again in "resource instances" to be considered
> "available"?
> 

Well, my original thinking was that the API documentation was used to give hints about the current set of 'possibly' supported operations for a 'hydra:class', whereas an instance representation would provide a more concrete set of hints about the operations supported by that instance at that point in time.

But I think I understand your point - i.e. the general case would certainly be that most instances would support all the operations stated in the API documentation for their class anyway, so why restate that API documentation for almost every instance. But am I correct then in my assumption above that the only purpose for having resource instances being able to state supported operations is for them to state 'extra' or 'new' operations that they *do* support, but that may not have been stated in the API documentation for their 'hydra:class'?

And if that assumption is correct, then is it even possible for a resource instance to give a hint that it explicitly does *not* support a specific operation that *is* stated as supported in the API documentation for that instance's class? (For instance, the API documentation might state that the 'Products' class may support a 'Special Discount' operation, but a specific instance of 'Product' will only support that 'Special Discount' operation if the user associated with that instance is a 'Privileged User'...?).

I know a resource instance can always reject a request at runtime for 'Special Discounts' if the user is not 'Privileged' (and I know we have the open-world assumption to deal with here!), but I think like Tomasz I was kinda thinking of a UI that could be a bit friendlier than always offering the user every possible operation, but then returning errors to them when they attempt operations that the server-side probably knows already that they can't actually perform...

> 
> Cheers,
> Markus
> 
> 
> [1] http://lists.w3.org/Archives/Public/public-hydra/2014Jun/0075.html

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

Received on Monday, 7 July 2014 17:16:03 UTC