Re: URI design, part 2

On Dec 4, 2012, at 11:40 PM, Max Toro <[email protected]> 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 <[email protected]> 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
> 



------------------------------------

Yahoo! Groups Links

<*> To visit your group on the web, go to:
    http://groups.yahoo.com/group/rest-discuss/

<*> Your email settings:
    Individual Email | Traditional

<*> To change settings online go to:
    http://groups.yahoo.com/group/rest-discuss/join
    (Yahoo! ID required)

<*> To change settings via email:
    [email protected] 
    [email protected]

<*> To unsubscribe from this group, send an email to:
    [email protected]

<*> Your use of Yahoo! Groups is subject to:
    http://docs.yahoo.com/info/terms/