First of all, this piece was written in 2008.

The tl;dr is that GET/DELETE/PUT are idempotent, whereas POST is not. The author suggests that POST should be used on "collection-like" resources, e.g. '/Persons' to create a new Person while PUT to update/create a specific Person (i.e. you know the identifier of the Person in the system). Multiple PUTs on that resource, with the same payload body, will not change the state of system.

This makes sense, and, as far as I have seen, is the "normal" way to approach REST (for various definitions of REST). What puzzles me is that the first referenced article ("How to Create a REST Protocol") actually doesn't advocate the PUT=CREATE mapping. Maybe I am missing something?

Reaching the article's concluding paragraph, the author states: "PUT must create or update a specified resource by sending the full content of that same resource". OK, but this complicates matters, since the client now needs to know how to address a particular resource i.e. have implementation/domain-specific knowledge.

My approach is using POST to create, and PUT to update (NOT create/update). I find that it simplifies things quite a bit.

Aside from my HTTP/REST rant, I think there's a much better discerning factor between POST and PUT. From the HTTP spec:

"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. [...] 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. If the server desires that the request be applied to a different URI, it MUST send a 301 (Moved Permanently) response; the user agent MAY then make its own decision regarding whether or not to redirect the request."

So if you want to create the user Foo and you somehow know about the URI example.com/users/Foo, then you can directly PUT your information to that URI. This URI points directly to the enclosed entity, the user. If you only know the URI of the enclosing resource (aka collection), then you MUST do a POST to example.com/users/.

So that's the semantics of it, PUT deals directly with the resource that the URI points to, while POST deals with a collection of subordinate resources.

However, the REST catch is that if you follow the HATEOAS principle, there's (almost+) no way you would know about example.com/users/Foo. In the REST world, you would (almost) never use PUT for creating, because if that resource doesn't already exist, you would (almost) never get a URI to it by traversing the hypertext representation of the application state.

+ I say almost because you could have something like a GET example.com/users?name=Foo that would return 404 with the URL where to PUT to create this user. Not sure how HATEOAS proposes you get to a URL like example.com/users?name=Foo though, perhaps someone more knowledgeable can pitch in.

It seems to me that these discussions produce far more heat than light. If one needs to build an application, what is the benefit to sweating these details to such an extent? I don't mean to denigrate any of the fine work that's gone to figuring out these standards. But if the application and/or API works well, what difference does it make whether it uses post or put? I honestly would like to be enlightened. Is the motivation to make it so that people will know how api's work without reading about them, because they conform to a clear standard that everyone understands? If so, that hardly seems achievable. So I've honestly been long perplexed why people sweat this type of thing so hard.

Are there any examples of REST API implementations that are actually true to the original concepts or is everything kind of a "Web API" compromise? As a follow up, does, and should, anyone actually care really?

Is REST really just a pipe-dream in practice?

Good we have PATCH[1] now ;) .

[1] http://tools.ietf.org/html/rfc5789

The issue this piece exposes is much wider than REST and completely independent of the validity/desirability of REST. The semantics of PUT and POST are defined in the HTTP spec, a much lower level than the architectural one at which REST exists. As such, everyone developing HTTP-enabled code SHOULD (RFC 2119) obey the proper semantics to make sure we all use the same vocabulary. I mean, c'mon guys, there's only a handful of verbs!

This is HTTP not REST. You need to understand this even if you're against REST.

(edited to remove tl;dr. It looked much longer in my text box)

I'm curious how security is typically handled in REST setups.

Wouldn't you want to have some nonce anyway on requests that modify resources (and thus allowing idempotency even if you POST everything) ?

Or are resources typically protected purely by some non-HTTP auth process, i.e. a custom header, or username/password/API key provided as POST data?

If sending data to a resource is protected via simple basic authentication then you can use a auto-posting form to send it on behalf of a user, if they previously entered this data for testing in their browser. I.e. basic cross-site request forgery.

Does anyone else think the naming of PUT/POST actually makes things more confusing? I feel like if they were better named at least a little confusion would be cleared up.