Re: Specifying operations for instances

On Fri, Jun 13, 2014 at 12:33 AM, Markus Lanthaler <markus.lanthaler@gmx.net> wrote:
> 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.
>

Ah yes, of course I saw that in the examples. However this method is
not relevant here. Although on the other hand absence of a property in
resource's representation would be an additional way to fine tune what
actions the client can take...

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

I see the ApiDocumentation as a description of classes and their
operations. It is to class' behavioral model what ontology is to it's
structural model. In fact I think that ApiDocumentation should contain
a complete description of *all* possible operations on described
classes. It is as the name implies a documentation. The problem is
that it is not enough to decide which operations can be actually
invoked on a specific resource given tis current state of application
state. A not-so-generic client will want to adapt to the circumstances
rather than offer the users all possible options every time. Or even
worse there will be an incentive to write out-of-band code on the
client side logic such as "if the authenticated user is not a
moderator, don't show the form to moderate a forum post".

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.

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

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

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?

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

In fact it does, but usually that messy code is the view itself, be it
Velocity, Razor, Haml, JSP or whatever sprinkled excessively with
logic which decides that specific links and forms should or should not
be present based on model state and application state.

Now if we want to include all that information in the model itself,
that logic must be moved from views to model, controller or somewhere
else. Come think it again I may have come into conclusions too quickly
about such code being messy. That would depend on the developer and
possibly the web framework but as always there would be a number of
ways to achieve the desired result. Case closed :)

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

Regards,
Tom

>
> Cheers,
> Markus
>
>
> [1] http://en.wikipedia.org/wiki/Open_world_assumption
>
>
> --
> Markus Lanthaler
> @markuslanthaler
>
>
>
>
>

Received on Saturday, 14 June 2014 19:11:53 UTC