RE: Specifying operations for instances

Tom, you didn't send the reply to public-hydra but just to me. I forwarded your mail to the list so it gets archived properly (and everyone gets it)

On 13 Jun 2014 at 10:02, Tomasz Pluskiewicz wrote:
> On Fri, Jun 13, 2014 at 12:33 AM, Markus Lanthaler wrote:
>> On 11 Jun 2014 at 20:38, Tomek Pluskiewicz wrote:
>>> The first is to use the supportedOperations property on the Class
>>> resource. This gives the client a general view on all possible
>> 
>> Please note that we operate under the open world assumption [1]. This means, you have to
> acknowledge that you don't know if these are *all* possible operations or just a few of
> them. You just know that the ones you see are possible.
>> 
> 
> Open world assumption doesn't help much here. I see the analogy to

It doesn't help but it is important to understand it. You wrote in your initial mail (emphasis mine):

    "This gives the client a general view on **all** possible
     interaction with all resources of that type.

I just wanted to make sure we are on the same page.


> predicates' domains and ranges. Given a predicate with a domain class
> specified doesn't however imply that every single instance of that
> class will actually exist in such relationship.

Right


[...]
> Also IMHO the open-world assumption doesn't work here. It implies that
> the clients can actually send any request to the server, because there
> *could be* more operations. However the server doesn't operate under
> OWA and will reject requests that are not supported.

The server does what it does. You won't know for sure before you try it. It is a distributed system and you don't control the server. Furthermore, an API can point to resources in other APIs.


>>> I'd like to know your opinion/guidelines about some details:
>>> 
>>> 1. Let there be a class, which supports operations X and Y. Let there
>>> be an instance of that class, whose representation has operation X
>>> included directly in it's representation, but not operation Y. Should
>>> the client in such case assume that operation Y is not allowed on the
>>> that resource?
>> 
>> No. The client should interpret things exactly the same way regardless
>> of where/how they are defined. In this case, both X and Y should be
>> 
> 
> It's like saying the every HTTP resource has the GET, POST, PUT, PATCH
> etc actions supported and one should assume that they are supported. But

Why is it the same?

You explicitly state that a resource is of a certain type. You also state that all instances of that type support operations X and Y. Finally, you state again that that specific resource supports operation X. Why should that imply that Y isn't supported?


> it doesn't mean that every single resource will allow any request.
> That's where OPTIONS come in the case of raw HTTP. If I were
> implementing a client, I would expect explicit information what
> operations I can perform next and not guess based on all possibilities.

See above. You get explicit information. Obviously you need to use it correctly, but that applies to everything - including OPTIONS.


> And actually I'm surprised that you would treat supportedOperations
> and operation properties equally. If so why actually have two
> properties in the first place?

If there would just be one property, "operation", what would

    http://www.example.com/a/Class operation ....

mean? Would it mean that all instances of that class support that operation? Or would it mean that http://www.example.com/a/Class supports that operation? Having two properties makes this unambiguous.


>>> What do you think about using the
>>> OPTIONS verb instead and in returning the operations in response. This
>> 
>> I'm not a big fan of OPTIONS. It has several severe drawbacks... e.g.
>> it requires you to make two requests for each resource and it isn't
>> cacheable.
>> 
>>> way every resource can have it's own set of available operations based
>>> on for example it's state or the user's permissions and at the same
>>> time the server side code keeps a clear separation of concerns. Would
>>> you think that the benefits outweigh the costs of additional traffic?
>> 
>> No. The simpler and cleaner approach is to bind operations to classes or properties in the
> API documentation and then dynamically add/remove those classes/properties from the
> resources. Think of something like "PublishedBlogPost". It's very cheap to create new types
> and clients don't need to understand them in order to find the operations. Have you thought
> about that already?
>> 
> 
> +1
> This is actually as neat idea and no, I haven't thought about that.
> 
> 
> I think I see your point better now. You suggest that the application
> could keep the ApiDocumentation and then choose whatever relevant
> operations should be added to a resource instance? I agree that it's

You have the choice. You can describe all operations in the API documentation if you want and then add/remove them from resources by
  - asserting that the resource is/is not an instance of a specific classes
  - add/remove properties from the representation
  - reference those operations directly from the representation


> up to the client to interpret it as it sees fit. However I still think
> that Hydra itself should be a more precise tool with if not rules, at
> least some guidelines on the semantics behind operations.

This doesn't make Hydra less precise. It just means that there are multiple ways to achieve the same thing. Generally, we should try to avoid that but in this specific instance I think it's a quite valuable feature.

I don't really understand what you mean by "if not rules". What " guidelines on the semantics behind operations" are missing in your opinion?


--
Markus Lanthaler
@markuslanthaler

Received on Saturday, 14 June 2014 19:20:51 UTC