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

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

Expand Messages
  • Eric J. Bowman
    Nov 30, 2012
      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.

    • Show all 28 messages in this topic