Re: URI design, part 2

This post is mostly aimed at Max Toro, but Eric provided a nice entry point
for me :-)

On Sat, Dec 1, 2012 at 8:08 AM, Eric J. Bowman <[email protected]>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.
> >
>
> Well, what are you expecting to GET from /cancel, or are you just using
> that URL to invoke a procedure? [...]
>
 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."
>

Exactly.  And we don't know what the author intends to identify just by
looking at the path /orders/1/cancel.

Just looking at the syntax of a single request (e.g. the method POST and/or
the path /orders/1/cancel) is not enough to determine if the system adheres
to any particular architectural style.

The author may well intend that /cancel identifies a resource, and allow
lots of interaction in it.  It might even have an HTML representation, with
a nice <form method="post"><input type="submit" value="CANCEL"></form> in
it.

But this is still not enough to determine if a system adheres to the
constraints: For even though the server provides such hypermedia controls,
media types and does everything "by the book", it is still up to the
*client* to actually *use* these hypermedia controls.  In fact it is up to
the author of the agent itself.

If you write code in the client that hard wires a button called "cancel" to
the "POST /orders/1/cancel" HTTP request then the client isn't really
honouring the hypermedia controls laid out above.  If, however, it _soft
wires_ the same button _because_ of the hypermedia control above, then
you're doing it "more right" I would say.  The point is that the client
should be written in such a way that it uses _only_ the hypermedia controls
that it receives at run-time.

Roy's thesis really must be considered in its entirety, [...]
>

+1 to such a degree that 1 > 1.  The rest of the stuff you wrote was great.
 I just want to highlight the incorrectness of the question, as others said
earlier that REST doesn't say anything about if POST /foo is or isn't...
 For all we know /orders/1/cancel is a picture of a dog, or it could be a
SOAP endpoint for a nice game of Global Thermonuclear War.

The constraints of REST are too often thought / taught to deal with the
server side, but in my experience, it has much more to do with the client
side, how much knowledge the client has on things like:

- what URLs can it use? (it shouldn't know any; but bind to one at
run-time, preferably via a configuration parameter)
- when it knows one URL (e.g. "/orders/1"), can it add "/cancel" to it to
cancel it?  (no, unless it was told to add "/cancel" by a hypermedia
control)
- does it know the "type" of a resource, e.g. that /orders/1 is an Order
(this is a point of contention on the list; browsers don't know about books
or a bank account, but work fine nonetheless.)
- when it does know the type of the URL is an order, does it pull up a
pre-coded "order" UI (bad), or does it create a UI based on what it finds
in the response (good)


-- 
-mogsie-