I'm well into implementing a REST service (on a Windows CE platform if that matters) and I started out using IBM's general definitions of using POST for creating (INSERTs) and PUT for updating.
Now I've run across Sun's definitions which are exactly the opposite. So my question is, which is the "generally accepted" definition? Or is there even one?
We use POST= Create, PUT= Update.
Why? There's no good reason. We had to choose one, and that's that choice I made.
Edit. Looking at other answers, I realize that the key creation issue might make the decision.
We POST new entries and return a JSON object with the generated key. It seems like this is a better fit for generally accepted POST semantics.
We PUT to existing entries with a full URI that identifies the object.
The disadvantage of using PUT to create resources is that the client has to provide the unique ID that represents the object it is creating. While it usually possible for the client to generate this unique ID, most application designers prefer that their servers (usually through their databases) create this ID. In most cases we want our server to control the generation of resource IDs. So what do we do? We can switch to using POST instead of PUT.
So: Put = UPDATE
Post = INSERT
PUT can be used for creation when the server grants the client control over a portion of its URI space. This is equivalent to file creation in a file system: when you save to a file that does not yet exist you create it and if that file exists the result is an update.
However, PUT is lacking the ability of an implicit intent of the client. Consider placing an order: if you PUT to /orders/my-new-order the meaning can only ever be update the resource identified by /orders/my-new-order whereas POST /orders/ can mean 'place a new order' if the POST accepting resource has the appropriate semantics.
IOW, if you want to achieve anything as a side effect of the creation of the new resource you must use POST.
Jan
The reason to use POST as INSERT and PUT as UPDATE is that POST is the only nonidempotent and unsafe operation according to HTTP. Idempotent means that no matter how many times you apply the operation, the result is always the same. In SQL INSERT is the only nonidempotent operation so it should be mapped onto POST. UPDATE is idempotent so it can be mapped on PUT. It means that the same PUT/UPDATE operation may be applied more than one time but only first will change state of our system/database.
Thus using PUT for INSERT will broke HTTP semantic viz requirement that PUT operation must be idempotent.
Here http://www.w3.org/Protocols/rfc2616/rfc2616.html is the offical guide of how to implement the behaviour of the HTTP methods.
The verbs are:
GET {path}: Retrieve the resource whose identifier is {path}.
PUT {path}: Create or update the resource whose identifier is {path}.
DELETE {path}: Delete the resource whose identifier is {path}.
POST {path}: Invoke an action which is identified by {path}.
When the intention is to create a new resource, we can use PUT if we know what the identifier of the resource should be, and we can use POST if we want the server to determine the identifier of the new resource.