RE: Specifying operations for instances

On 7 Jul 2014 at 19:15, McBennett, Pat wrote:
> Markus Lanthaler wrote on July 07, 2014 5:03 PM:
>> On 3 Jul 2014 at 23:40, McBennett, Pat wrote:
>>> ...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...?

Yeah, that's true and is a direct consequence of the underlying open world assumption:

  http://en.wikipedia.org/wiki/Open_world_assumption


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

Correct.


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

No, that's not what was intended.


> 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

Right, that was the motivation behind this feature. If that wouldn't be the case, I would have left that feature out.


> 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'?

Yeah, that's correct. Think of comments on a blog. There will be lots of them, but there are only very few that you wrote. Thus, it would make sense to state that a specific comment can be DELETEd by you in the resource representation.


> 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

No, that's currently not possible. The client has to try to invoke the operation to find that out.


> 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'...?).

This can be addressed by serving different API documentations to different users.


> 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

There are multiple ways to achieve that:
  - just use inline operations
  - use inline operations for things that vary by user/instance/etc.
  - serve different API documentations for different users
  - use multiple classes and use them accordingly (Comment, RemovableComment)



--
Markus Lanthaler
@markuslanthaler

Received on Monday, 7 July 2014 17:52:05 UTC