Re: URI design, part 2

Nicholas Shanks <[email protected]> Fri, 30 Nov 2012 18:08:40 +0000
Newsgroups	gmane.comp.web.services.rest
Message-ID	<[email protected]>
On 30 Nov 2012, at 13:15, Max Toro wrote:

> Thanks for your answers, it's pretty much what I had in mind.
> 
> I want to discuss a second example:
> 
> a)
> POST /orders/1/cancel
> 
> vs.
> 
> b)
> PATCH /orders/1
> 
> canceled=true
> 
> 
> Does REST say anything in favor or against these two designs?

REST says "Do 'b', never 'a'." Sorry!
The simple rule is URIs are for nouns, HTTP methods are for verbs.

You could get away with this though:

POST /orders/1
cancelled=true

Originally, POST was intended to mean "post a reply" the same as it's NNTP namesake/predecessor. Now, though, the authors of HTTP concede that it's modern meaning is "Hey, server, use these data (request body) to perform some action to this resource (uri)"

As such, by POSTing to /orders/1 you are at least getting the resource part of the API right, even if you are lacking the semantics of a PATCH request.

> Personally, I would never do 'b' because it's simply hard to implement
> with the tools I use. Also, isn't it a case of tunneling? 'Cancel' is
> an action that does more than simply update a resource.


I wouldn't call it tunnelling, tunnelling would be something like:

POST /orders/1

_method_override="DELETE"    // could also be custom HTTP header

If the "cancel" action is just updating a resource state, rather then, say, DELETEing the resource, then you could even do something like:

PUT /orders/1/cancelled
true

(again, use POST if you can't PUT)

and correspondingly:

GET /orders/1/cancelled

=> "true"

GET /orders/2/cancelled

=> "false"

(or 1/0, yes/no, … however you wish to represent it)


For reference, stackoverflow.com is a good place to go with these sorts of questions. Many have already been asked in various forms, you'll find the answers already provided.

— Nicholas.


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

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/