I'd humbly submit that PUT is the better choice. POST is to create the resource, PUT would be better to change its state. I don't want to make a new horn, just honk the one thats there. (PUT is also usually considered idempotent, honk as much as you want!)
POST doesn't have to create a resource; it can also be used to annotate existing resources.
The main problem with using PUT is that PUT is supposed to be idempotent; the result of two PUTs with the same content should be the same as the result of a single PUT with that content. But two PUTs to honk the horn would honk the horn twice, not once.
Since we're all being pedantic about HTTP methods here, we should have a link to RFC 2616 :)
Ahh. Good point. I was considering PUTting the horn into the honking state vs POSTing horn honks for execution. In the first case, 2 PUT honks would just result in a honking car, in the second, 2 POSTs would get you 2 "honks" whatever those are defined to be.
I guess I was thinking of the idempotent "panic" button on my cars key fob.
PUT can be creation (not only POST), if you know the URI of the resource in question, but PUT implies that the submitted data should create or replace the resource at that URI, and in the case of a physical horn, this is impossible. I don't think you should ever be able to PUT to something that it's impossible, even in theory, to create with a PUT.
First of all, we're not "enclosing" an "entity" to be "stored" or "accepted", so neither HTTP verb is strictly appropriate.
PUT requests are for uploading a resource, and the uploader specifies the desired final URL. So PUT is only appropriate for creating a new horn. Relevant quotation:
In contrast [with POST], 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.
POST requests, by contrast, are sent to a handling resource, which decides what to do. POST is appropriate for several purposes, including "annotating existing resources" and "providing ... data ... to a data-handling process". Seems like a better fit.
But either way, REST is for documents (understood broadly), and I don't think I know how to understand "document" broadly enough to cover a horn. So it's gonna be a rough stretch, and in general, I'm skeptical about the value of applying REST semantics.
>But either way, REST is for documents (understood broadly), and I don't think I know how to understand "document" broadly enough to cover a horn. So it's gonna be a rough stretch, and in general, I'm skeptical about the value of applying REST semantics.
That's probably about the wisest thing that's going to be posted on the subject tonight. I did a large enunciator panel project and we ended up being "rest-ish", using the idempotent PUT to put hardware dodads into various states, and reserving POST for adding things to execution queues. Being clear and consistent is probably the silver pearl in any implementation. Hardware control always degrades to some kind of RPC scheme, even if you dress it in a REST outfit.
> I'm skeptical about the value of applying REST semantics.
One must at least take the basic protocol promises into account. And there is no certainty that a GET will reach its destination, nor that it (or a PUT) will reach destination only once.
I agree absolutely; if you're using HTTP, you must take into account HTTP semantics. Exactly as you said.
But HTTP is not REST (note that SOAP usually layers over HTTP, although the SOAP-vs-REST is an unhelpful dichotomy).
As some other commenters (including an uncle of this comment) have said, what one often wants is simply RPC, and one must pick (or roll) an RPC format. JSON-or-whatever over HTTP seems good to me, and yes one must be respectful of HTTP semantics.
In fact, aside from the very-troubling choice of GET for commands, the API linked seems entirely reasonable. And it's not RESTful at all (in ways far deeper than verb choice). And that's a good thing.
