CODEWITHSUNDEEP
asp.netweb-servicesrest
ctacke
ctacke

Reputation: 67178

REST verbs - which convention is "correct"

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?

Upvotes: 21

Views: 4886

Answers (7)

Herbert
Herbert

Reputation: 5778

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.

Upvotes: 1

Volodymyr Frolov
Volodymyr Frolov

Reputation: 1306

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.

Upvotes: 17

yfeldblum
yfeldblum

Reputation: 65435

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.

Upvotes: 6

Darrel Miller
Darrel Miller

Reputation: 142014

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

Upvotes: 2

S.Lott
S.Lott

Reputation: 391818

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.

Upvotes: 2

Jan Algermissen
Jan Algermissen

Reputation: 4978

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

Upvotes: 5

Cristian Boariu
Cristian Boariu

Reputation: 9621

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

Upvotes: 21

Related Questions