Quick summary: PUT is idempotent, and should be used when you're sending the full text or properties of an item, or otherwise doing some where doing it a second time is harmless. POST is not, and should be used for requests like "increment this field" or "add a new sub-item to this parent item" where doing it twice will give a very different result than doing it once.
Personally I feel that idempotence should be the only important semantic component of PUT.
Although the spec makes stronger assertions about its semantics than this, namely that the body of a PUT is supposed to a full replacement for the resource at the URL in question.
However I don't think any clients or middleware take advantage of this or would reliably be able to take any useful advantage of this.
Whereas idempotence is something which client and middleware can usefully take advantage of - eg a browser can safely re-try an idempotent request whereas it can't safely retry a general POST.
Allowing PUT to be used for requests which are idempotent but not technically full replacement updates (eg partial updates) would allow middleware to know that they're safe to repeat.
By constraining the use of PUT to 'full replacement' updates, you deny people a useful way to signal idempotence for other more general kinds of idempotent updates.
"PATCH is neither safe or idempotent as defined by [RFC2616] Section 9.1."
The only semantics it has seems to be "change this resource in some way". Sometimes such a change might be idempotent, sometimes not, and the PATCH method provides no way of communicating this.
Personally I see little advantage from adding a PATCH method. Its semantics, as far as any generalised client software or middleware are concerned, seems the safe as POST.
Really the question which this raises is: for what reasons are new REST methods justified?
I think Fielding et al are vague on this topic, and I think the vagueness shows in HTTP (and in proposed extensions like PATCH)
Personally I think new methods should only be justified where they have generalised semantics which can be exploited by middleware (or middleware-like layers in client software) and where no existing method is available to express these semantics. Terms like 'safe' and 'idempotent' are relevant and useful properties to consider at this level.
The data-level semantics (like 'applies a diff to' or 'does something approximately like a full update to') aren't really relevant when it comes to request methods, unless they are properties which it's genuinely useful for generic middleware to know about.
I say this because hypertext and standardised hypertext media types and relations are already great at helping people discover available operations, together with their data/domain-level semantics, without the need for any new request methods.
The idempotency of the patch is determined by the content-type of the request entity, instead of being inherent to the method. The idempotency and safety of GET, DELETE, and PUT are shaky too, because Fielding and others say that side effects of these methods are not required to be idempotent. Really everything about the semantics of HTTP is very hand-wavy.
I believe that PATCH was created because people couldn't come to a consensus on whether PUT was required to replace the whole entity or whether it was allowed to have patch-like abilities.
Hm, yeah the wording when it comes to idempotence does seem slightly vague now I look at it again; SHOULD, rather than MUST in the RFCs at least.
It is hand-wavey isn't it. The whole REST concept smells of post-hoc generalisation based on just one significant example, HTTP, and as such there seems to be a lot of confused but zealous hermeneutics involved in determining the One True RESTful Way To Do HTTP both from the HTTP RFCs and Fielding's other writings (which can be rather pompous and/or opaque).
Instead, I'd like if people went back to first principles and thought hard about what actual value certain kinds of semantics have which justify (or don't justify) making them part of the protocol, as opposed to just standardising the semantics as part of some media type or other.
Idempotence, to me, seems like something which is genuinely useful and justifies itself as part of a transfer protocol, so I'd like to see HTTP take a clear and useful stance on it.
Weird that calcnerd256 is being down-voted for linking to w3.org while mjw is being up-voted for expressing personal feelings.
Here's the relevant paragraph from the w3.org link:
The fundamental difference between the POST and PUT requests is reflected in the different meaning of the Request-URI. The URI in a POST request identifies the resource that will handle the enclosed entity. That resource might be a data-accepting process, a gateway to some other protocol, or a separate entity that accepts annotations. In contrast, the URI in a PUT request identifies the entity enclosed with the request -- the user agent knows what URI is intended and the server MUST NOT attempt to apply the request to some other resource.
I'd say the mapping is good enough. PUT updates a current object, which can be done again. POST creates a new object which can't be repeated without producing another article. CouchDB has automatic versioning which is mostly transparent to most operations. (on a single instance)
It was a nitpicky comment, I guess cause I am contemplating the meaning of idempotent. Two identical PUTs on an existing doc will not change the database so I guess that's OK, but their response will be different insofar as the 2nd will fail.
I don't think the failed response matters. You can replay a PUT request without altering the state on the server. (Aside from the single object you're manipulating.) Replaying a POST gets you two objects with the same data.
It's not so much about caching - it's more about knowing that you're safely able to repeat a request which timed out or failed.
A way to distinguish form submissions (like a credit card purchase form) which must not be repeated after submission, from things like "upload a new version of this file" which you can safely allow to be retried if they time out or fail.
This is potentially useful for a bunch of different HTTP clients and client libraries, and potentially for some proxies too.
Edit: actually PUT and DELETE are useful for caches - although not because of their idempotency, but just because they communicate the fact that the resource being PUT to or DELETEd may change as a result, hence the cache key for that URL should be purged. IIRC some caching proxies do do this.
Hehe, a proxy cashing PUTs can spice up your REST experience. How exactly will the proxy know someone else haven't updated a resource between 2 requests and it's safe not to pass the 2nd request to server?
I can't agree with last few paragraphs. "Location" header should be used for redirections. There is "Content-Location" header which should be used to identify real location of the content.
So, for example, for newly created objects ("POST /objects/"), you should return content with header "Content-Location: http://website.com/objects/object_id ".
"If a resource has been created on the origin server, the response SHOULD be 201 (Created) and contain an entity which describes the status of the request and refers to the new resource, and a Location header (see section 14.30)."
it's worth remembering that firefox won't let you PUT an attachment from a form, it must be POST which is a real pain for dealing with couchdb sometimes
Not just Firefox - all HTML 4 forms support only GET and POST (though XMLHttpRequest supports any method.) HTML 5 forms do support PUT and DELETE though not HEAD. (I think this is accurate. Corrections appreciated.)
People who don't know anything about building distributed systems hop on the REST bandwagon and before you know it they've got a monstrosity that doesn't work.
I come in as a $150 an hour consultant, explain really clearly that it's ~very~ hard to get business rules and transactions working right in a REST situation, re-architect the system with POX RPC and get it working.
When I see blog entries about the "finer points of REST" I hear ka-ching, ka-ching, ka-ching!
You're obviously (by your rate and believes) a newcomer to enterprise architecture ;) Distributed transactions are an anti-pattern even with WS-Transactions. And business rules belong to the services themselves, not to the service infrastructure.
If only SOAP wasn't the face of RPC to most people, you probably wouldn't get downvoted so hard. ;) SOAP is horrible but REST is worse. JSON-RPC is elegant and simple. I wish more people would use it.
Well distributed transactions in some mission-critical enterprise setting isn't what REST is all about, not even close. If people are really making that mistake fair play to you.
I would hope that the majority of us out there using REST have a sense of perspective about it though. It's about providing services as part of the open web in a loosely coupled, organic, discoverable fashion based on standardised media types. And also about implementing lightweight APIs which observe the semantics of HTTP rather than layering stuff on top of it.
This kind of stuff is a great fit for a lot of APIs which face the open web, or which are used by clients without hard, business-critical constraints on reliability and transactionality. The semantics of HTTP obviously weren't designed for that stuff, although they do contain some features which go part-way towards helping, which is perhaps what sets some people on a slippery slope.
