RE: Specifying operations for instances

Hi Tom,

On 11 Jun 2014 at 20:38, Tomek Pluskiewicz wrote:
> The Hydra documentation gives two way for informing the client about
> available operations for a resource.

Actually there are three. The third is to bind an operation to a property (think link relation type). It then applies to all values of that property.


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

> interaction with all resources of that type.
> The other way is to use the operation property directly on an instance.
> 
> 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 assumed to be supported.


> Should the client even look at the Class's
> supportedOperations if operations are included in the resource itself?

Depending on what you mean exactly, yes. It should look at the ApiDocumentation (linked via the HTTP Link header) and use all the information it finds there. It doesn't have to dereference all class URLs to find out if they also define operations but it might try to do so. This is something we should discuss further.


> 2. I'm not very much in favor of including the operations directly in
> resource representation, because I think it makes for a messy or
> patched up server side code IMHO.

Why? In HTML this is more or less the only way to do it. Does it create "messy or patched up server side code"? Why not?


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


Cheers,
Markus


[1] http://en.wikipedia.org/wiki/Open_world_assumption


--
Markus Lanthaler
@markuslanthaler

Received on Thursday, 12 June 2014 22:33:45 UTC