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

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

Expand Messages
  • Max Toro
    Dec 1, 2012
    • 0 Attachment
      > 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.

      This is also explained on Subbu's book, chapter 2.6 "When and How to
      Use Controllers to Operate on Resources":

      "Problem: You want to know how to tackle write operations that involve
      modifying more than one resource atomically, or whose mapping to PUT
      or DELETE is not obvious. Solution: Designate a controller resource
      for each distinct operation. Let clients use the HTTP method POST to
      submit a request to trigger the operation... If the outcome is the
      modification of one or more existing resources, return response code
      303 (See Other) with a Location with a URI that clients can use to
      fetch a representation of those modifications."

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

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


      On Sat, Dec 1, 2012 at 4:08 AM, Eric J. Bowman <eric@...> wrote:
      > Max Toro wrote:
      >>
      >> What I'd love to get is an answer like: POST /orders/1/cancel is not
      >> REST compliant because chapter x of Fielding's dissertation explicitly
      >> or implicitly says it's not allowed or it's discouraged. After knowing
      >> what is or isn't REST then I'd love to learn more about the pros and
      >> cons of different architectural and implementation styles.
      >>
      >
      > 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."
      >
      > 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.
      >
      > Roy's thesis really must be considered in its entirety, to understand
      > the uniform interface constraint (of which identification of resources
      > is a sub-constraint). Chapter 1 introduces the notion of applying
      > design-by-constraint to networked software architecture, as inspired
      > by Eames IIRC. "A style is a named set of constraints on architectural
      > elements that induces the set of properties desired of the
      > architecture." (4.3)
      >
      > Chapter 2 defines terminology associated with networked software
      > architecture, which is required for understanding Chapter 3, which lays
      > out a methodology for evaluating various styles and applies this to
      > several examples. Most importantly, Chapter 3 identifies the
      > constraints associated with various styles, and describes the properties
      > they induce in a system (which may or may not be beneficial or
      > detrimental to the system you're designing; remember there is no best
      > architecture, only that which is best for your system). Which is of
      > course required for understanding Chapter 4.
      >
      > Chapter 4 considers the problems raised by the WWW, and suggests that
      > the architecture may be improved by applying design-by-constraint to it,
      > in order to address those problems. First, by identifying the desirable
      > properties of the early Web, and the constraints responsible for them;
      > next, by extending that architecture by adding additional constraints,
      > resulting in a new hybrid style consisting of aspects of existing
      > styles. Of course, this is required for understanding Chapter 5.
      >
      > "REST provides a set of architectural constraints that, WHEN APPLIED
      > AS A WHOLE, emphasizes scalability of component interactions, generality
      > of interfaces, independent deployment of components, and intermediary
      > components to reduce interaction latency, enforce security, and
      > encapsulate legacy systems." (4.4)
      >
      > 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...
      >
      > My point is, you'll have a much harder time trying to understand REST
      > by being told bluntly what is and isn't RESTful, than you will by
      > reading Roy's thesis in its entirety. As computer science dissertations
      > go, Roy produced a functional work of art, much as an Eames chair isn't
      > just a piece of furniture. Understanding what the constraints are, and
      > where they come from, is vital to understanding how they're applied to
      > the Web to derive REST, and why they must be implemented as a whole to
      > achieve REST.
      >
      > Only then will it become apparent when they're being violated, as in
      > the example given of POSTing to an unGETtable /cancel URL. That level
      > of understanding comes from the bottom up, not from the top down, IMO.
      > Knowing what is or isn't REST depends on understanding the pros and
      > cons of various architectural styles, because that's what constraints
      > are, and constraints must be understood before their application to the
      > Web as REST can be understood.
      >
      > More importantly, understanding REST as a style makes one a better
      > architect, because sometimes it's advantageous to deviate from REST's
      > constraints. Which is why I'm always on about how saying something
      > isn't REST is not a value judgment, just a fact. Understanding Roy's
      > thesis allows you to identify the constraints you have applied, and
      > understand that as its own architectural style derived from REST, to
      > use as a guide to developing that system -- but also to understand
      > which desirable properties of REST you're forfeiting in the bargain.
      >
      > Making informed decisions about which constraints to apply, is making
      > use of REST as a tool for long-term development. It may not be
      > feasible to apply all the constraints initially, if REST is truly what
      > your system needs. In which case your system design can account for
      > this, becoming more RESTful over time, instead of painting yourself
      > into a corner where the system needs re-architecting rather than
      > implementing another constraint as an extension.
      >
      > -Eric
    • Show all 28 messages in this topic