Re: URI design, part 2

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