Loading ...
Sorry, an error occurred while loading the content.

19213Re: [rest-discuss] URI design, part 2

Expand Messages
  • Jan Algermissen
    Dec 4, 2012
    • 0 Attachment
      On Dec 4, 2012, at 11:40 PM, Max Toro <maxtoroq@...> wrote:

      > Thank you very much for your responses Eric.
      >
      > The short answer is (if I understood correctly): POST /cancel is not
      > REST because it lacks visibility, since it's not possible to
      > understand the client's intent by examining the request.

      Maybe of interest: http://tech.groups.yahoo.com/group/rest-discuss/message/18998

      jan


      >
      > Never thought about HTTP/URI resource vs. REST resource, you say that
      > a URI that doesn't implement GET is probably (or always) not REST.
      > --
      > Max Toro
      >
      > On Mon, Dec 3, 2012 at 1:17 PM, Eric J. Bowman <eric@...> wrote:
      > > Max Toro wrote:
      > >>
      > >> > Well, what are you expecting to GET from /cancel, or are you just
      > >> > using that URL to invoke a procedure? If so, then there are a few
      > >> > places Roy's thesis admonishes against it in Chapter 6 -- the rest
      > >> > of REST is about positive, rather than negative, reinforcement of
      > >> > the identification of resources constraint. Suggested reading:
      > >> > 6.5.2; 6.2.1, in particular: "REST [defines] a resource to be the
      > >> > semantics of what the author intends to identify."
      > >>
      > >> To clarify, /orders/1/cancel is used to modify a resource, using POST.
      > >> A GET request would result in a Method Not Allowed response.
      > >>
      > >
      > > Yes, such examples are out there, but in them, /cancel is NOT a resource
      > > in the REST sense so they must be some style of RPC... REST, not so
      > > much. Representational State Transfer means just that -- resources are
      > > manipulated by transferring representations of their current, intended,
      > > desired etc. state. Chapter 5.4:
      > >
      > > "Requests and responses have the appearance of a remote invocation
      > > style, but REST messages are targeted at a conceptual resource rather
      > > than an implementation identifier."
      > >
      > > This example is a REST anti-pattern, as I cannot deduce the current
      > > (sub)state of the order (active or canceled) by dereferencing the URL
      > > I'm given for manipulating that (sub)state. Just making a toggle POST
      > > also fails to transfer any representation of anything, let alone
      > > application state, and isn't proper HTTP (which can never be proper
      > > REST).
      > >
      > > REST isn't about optimizing upstream traffic, it's about optimizing GET.
      > > What advantage does a subresource give when it contains no content from
      > > the parent resource? My goal with subresources is to increase the cache
      > > stickiness of their parent resources. Replace the subresource content
      > > in the parent resource, with a link or a hypertext control linked to the
      > > subresource. The link or hypertext control remains static, and cached,
      > > as the content of the subresource varies.
      > >
      > > That's a RESTful pattern, as the subresource now has a representation
      > > (other than that of the 406 error) we can transfer and manipulate to
      > > effect change of the parent resource.
      > >
      > >>
      > >> > Not the semantics of a method invocation. What does /cancel
      > >> > identify? Sounds to me like a method of tunneling DELETE through
      > >> > POST which identifies nothing, iow a procedure endpoint, which is
      > >> > characteristic of various styles but not of the REST style. The
      > >> > hypertext constraint only makes sense if your resources make sense,
      > >> > in that their URLs are identifiers rather than endpoints.
      > >>
      > >> If I understand correctly, you are saying that if I need to affect a
      > >> resource then I should use the uniform interface on that resource URI,
      > >> and not another URI.
      > >>
      > >
      > > Absolutely not! My example changed /order/1 by manipulating /order/1
      > > /status. The /order/1 resource includes its status, but its 200 OK
      > > representations only include links to the /status subresource, derived
      > > from the /order/1 resource such that manipulating a representation
      > > of /order/1/status updates /order/1 (on the server, you can do anything
      > > you want; on the client, the cached link/control in /order/1 now returns
      > > a different value).
      > >
      > > There's no cost to adding a URI like this, nor does it preclude changing
      > > order status via PUT/PATCH to /order/1. The difference is that /status
      > > uses REST's uniform interface, unlike /cancel. The /order/1/status URL
      > > is only presented within a hypertext control which explains how to
      > > manipulate it -- picture a drop-down list with the current status
      > > highlighted, meeting the hypertext constraint. You can always GET the
      > > status of an order even if you don't have a copy of that order, a
      > > useful separation of concerns beyond just optimizing GET, promoting
      > > serendipitous re-use.
      > >
      > >>
      > >> > Which brings us to Chapter 5, and the short answer to your question:
      > >> > "POSTing to /cancel violates the Identification of Resources
      > >> > constraint, and is therefore unRESTful." But I've found that just
      > >> > giving that answer tends to upset folks who've only read Chapter 5,
      > >> > then they get defensive about why can't they call their API
      > >> > RESTful, accusations of pedantry follow, and threads devolve into
      > >> > general ugliness, heheh...
      > >>
      > >> After reading that chapter again I'm not sure my example violates
      > >> anything, but I'd love to get more clarification from you. Is it the
      > >> use of a verb in the URI? or not using the URI of the resource I'm
      > >> trying to modify directly?
      > >>
      > >
      > > The biggest problem, is that an RPC endpoint which has no GET function
      > > while improperly listening for a method itself as a trigger rather than
      > > taking action based on the content of the entity required by that method
      > > and in obeyance of the semantics of that method, is so far away from
      > > REST that I don't know where to start except by urging that Roy's
      > > thesis be read in its entirety. Because it's obvious to me that this
      > > violates the first three uniform interface constraints, making adherence
      > > to the fourth irrelevant:
      > >
      > > "REST is defined by four interface constraints: identification of
      > > resources; manipulation of resources through representations; self-
      > > descriptive messages; and, hypermedia as the engine of application
      > > state."
      > >
      > > Note that "noun/verb" terminology is not present in the dissertation.
      > > But, yeah, if your URI is a "verb" you're probably getting REST wrong.
      > > There is no "cancel" method in the uniform interface. There are two
      > > basic means of solving this -- one, is refactor your cancel operation
      > > to use DELETE; two, tunnel your proprietary cancel method through POST.
      > >
      > > http://tech.groups.yahoo.com/group/rest-discuss/message/19210
      > >
      > > Making this operation its own URI doesn't make it more RESTful, as the
      > > resulting URI is only a resource in the HTTP/URI sense, but not the
      > > REST sense, of the term. Utilizing subresources to break out more
      > > dynamic aspects of content and cache them separately is RESTful; if the
      > > contents of the GET are also allowable content of a PUT then we're
      > > letting hypertext drive application state instead of listening for POST
      > > events to trigger server-object methods we've failed to refactor to the
      > > uniform REST interface.
      > >
      > > -Eric
      >
    • Show all 28 messages in this topic