RE: ISSUE-31: Are Operations violating REST's uniform interface constraint? (was: More Thoughts on Links and Operation Subclasses)

On Friday, February 21, 2014 6:46 AM, Mark Baker wrote:
> On Thu, Feb 13, 2014 at 3:14 PM, Markus Lanthaler wrote:
> >> It might choose, for
> >> example, to dispense with any error checking for 4xx since it knows
> >> that after a successful DELETE/Clear, that it will get back a blank
> >> page.
> >
> > Here you lose me. Why should it stop 4xx-error checking after a
> > successful DELETE/Clear? To make this crystal clear, are you saying
> >
> >   - the client invokes the DELETE/Clear
> >   - checks the status code of the response
> >
> > and *then* stops to check for 4xx errors? Why should it do so? What
> > would it do then if it tries to dereference such a resource and
> > get a 404? Would it break in a way it wouldn't otherwise?
> 
> Sorry, I see I wasn't totally clear in my description of the message
> flow. The flow I had in mind was;
> 
> - client invokes DELETE/Clear
> - client receives 200 response
> - client invokes GET on the same URI
> - client does not need to check for 4xx because of the semantics of
> "Clear"

Well, that's very arbitrary statement IMO. You could just as well say

  > - client invokes DELETE
    - client does not need to check for 2xx because of the semantics
      of DELETE

We are still interacting with a remote system. There are no assurances
whatsoever. We thus need to check the result of each and every interaction.
Having a little more information about some interactions doesn't change
that.


> >> That is the loss of visibility I mentioned, and results from
> >> extending the contract between client and server, rather than
> reusing the existing one.
> >
> > I understand in principle what you mean (the proxy doesn't know as
> > much as the client does) but can't see how that's a problem
> 
> I had a longer, more point-by-point response drafted to the rest of
> this message, but re-reading through it, realize that I should have
> just stopped you here, and mentioned that you don't have to see a
> problem to acknowledge that it isn't REST.

You are of course right, but that will lead us to a very theoretical
discussion. REST by itself, being an architectural style, is a very abstract
thing already. So we should mostly discuss things in terms of HTTP here.
Furthermore, IMHO, every solution should have a clear problem it is
addressing.


> It should suffice that one
> of REST's architectural properties has been found lacking to
> demonstrate that the solution isn't RESTful as you now know that at
> least one constraint that provides the property has been violated, and
> that there are problems relative to a RESTful solution. You can look
> for those problems if you want, but principled design tells us that
> there's no need. It can, however, be very helpful in understanding
> REST in-depth (I speak from experience).

OK, so, as an exercise, let me try to see if I find the constraint that
operations are violating. The uniform interface is defined by four
constraints [1]:

  - identification of resources;
  - manipulation of resources through representations;
  - self-descriptive messages;
  - and, hypermedia as the engine of application state

Let's look at all of them in the context of HTTP. In HTTP, resource
identifiers are URIs. We reuse that 1:1 in Hydra so that constraint is
honored. We also manipulate resource representations. No we come to two more
interesting constraints. Simply speaking, the self-descriptive messages
constraint demands that a message's semantics can also be understood by
intermediaries and the hypermedia constraint demands that the application is
driven by server-presented choices (links and forms). Operations have to do
with both of them. In a sense, they represent a hypermedia control which
presents a client a specific path forward. I don't think you are referring
to that though. I think you (and certainly Ryan) are concerned that Hydra
violates the self-descriptive messages constraint. Is that correct?

IMO self-descriptiveness can be looked at from at least two perspectives.
One is the HTTP interface, i.e., HTTP's semantics (method, headers etc.).
Another perspective would be to look into the body itself. I think you are
more concerned about violating HTTP's semantics (DELETE/Clear) whereas Ryan
seems to be more concerned about the body of a message
(AddItemToCartRequest). Let us concentrate on HTTP in this thread.

If I understand you correctly, you are saying that we are violating the
self-descriptive messages constraint when we define a ClearOperation and map
it to DELETE because we extend DELETE's semantics. An intermediary can't see
those extensions and thus the message isn't self-descriptive anymore. Is
that about right?

You are certainly right that the server "leaks" additional implementation
details to the client but my question is: does that really matter on an HTTP
level? None of DELETE's semantics are violated, i.e., it is not safe but
idempotent [2]. It is also in full conformance with HTTPbis [3]:

   [A DELETE] expresses a deletion operation on the URI mapping of the
   origin server, rather than an expectation that the previously
   associated information be deleted.

   If the target resource has one or more current representations, they
   might or might not be destroyed by the origin server, and the
   associated storage might or might not be reclaimed, depending
   entirely on the nature of the resource and its implementation by the
   origin server (which are beyond the scope of this specification).

Now all the operation does, is to hint the client what the server
implemented exactly. It describes the thing that is "beyond the scope of"
the HTTP specification. You can obviously misuse that feature, but what
can't be misused? Asked more concretely, how would Hydra have to changed so
that it wouldn't violate the self-descriptive messages constraint? Simply
saying "remove operations completely" doesn't count as you would lose the
ability to describe "forms".


Cheers,
Markus


[1]
http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5
_1_5
[2] http://www.iana.org/assignments/http-methods/http-methods.xhtml
[3]
http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-26#section-4.3.5


--
Markus Lanthaler
@markuslanthaler

Received on Friday, 28 February 2014 18:16:55 UTC