REST verbs - which convention is “correct”

Question

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)

Answer 1

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.

Answer 2

Here http://www.w3.org/Protocols/rfc2616/rfc2616.html is the offical guide of how to implement the behaviour of the HTTP methods.

Answer 3

I've been studying the concepts and implementations of REST a lot lately and the general consensus seems to be: PUT is used for creating/updating depending on whether or not the resource already exists. POST is used to append a resource to a collection.

See HTTP/1.1 Method Definitions http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html

POST is designed to allow a uniform method to cover the following functions:

  - Annotation of existing resources;

  - Posting a message to a bulletin board, newsgroup, mailing
    list, or similar group of articles;

  - Providing a block of data, such as the result of submitting a
    form, to a data-handling process;

  - Extending a database through an append operation.

The PUT method requests that the enclosed entity be stored under the supplied Request-URI. If the Request-URI refers to an already existing resource, the enclosed entity SHOULD be considered as a modified version of the one residing on the origin server.

Also see the accepted answer to the question at Understanding REST: Verbs, error codes, and authentication.

Answer 4

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

Answer 5

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

Answer 6

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.