21

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?

ctacke
  • 66,480
  • 18
  • 94
  • 155

7 Answers7

21

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

Cristian Boariu
  • 9,603
  • 14
  • 91
  • 162
  • While this gives a good reason as to why someone might use Post for Insert, it doesn't really establish this as a standard. The id generation isn't a problem for anyone using Guids. Perhaps the right answer is that there is no generally accepted standard. You can use the HTTP verbs as you see best fit to implement a service that respects the REST principles. – srmark May 18 '11 at 00:02
17

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.

Volodymyr Frolov
  • 1,256
  • 5
  • 16
  • 25
  • Not entirely true. If you look at Cristian Boariu's answer. When using PUT to insert while the client provides the ID, the second PUT with the same ID would overwrite the newly created resource instead of creating a new one. This would keep the operation idempotent. – Matthijs Wessels Jun 03 '13 at 23:11
6

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.

yfeldblum
  • 65,165
  • 12
  • 129
  • 169
  • Your definition of POST contradicts both of the documents I linked to. It also seems to indicate using a verb which, I believe, is discouraged – ctacke Mar 15 '10 at 19:58
  • 1
    You are correct. My definition contradicts both IBM's and Sun's definitions, because both IBM and Sun got it wrong. Please see the table of samples and meanings at http://en.wikipedia.org/wiki/Representational_State_Transfer#RESTful_web_services – yfeldblum Mar 16 '10 at 02:53
  • Please note that `GET`, `PUT`, and `DELETE` are standard hashtable (JavaScript object, Ruby hash, Python dict) operations. On hashtables, these methods are all idempotent. Contrariwise, `POST` invokes the image of invoking a complex method on a service, rather than performing a simple operation on a hashtable. Indeed, `POST` is intended for all use cases where the three simple hashtable operations (`GET`, `PUT`, and `DELETE`) are insufficient. – yfeldblum Mar 16 '10 at 03:11
5

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

Jan Algermissen
  • 4,930
  • 4
  • 26
  • 39
2

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.

S.Lott
  • 384,516
  • 81
  • 508
  • 779
  • Basically just choose one and run with it then. That what I (inadvertently) did - just wanted to make sure I wasn't going to confuse all of my customers by choosing the inverse of common practice. – ctacke Mar 15 '10 at 14:14
  • "customers"? Please update your question to explain who might be confused. – S.Lott Mar 15 '10 at 16:08
  • 1
    By "customer" I mean if I create this service for my customer (he who is paying for the work, not the service consumer app), then they go on and want to extend it and add more services they don't end up feeling my use of POST/PUT are backward from everything else they're seeing as examples. – ctacke Mar 15 '10 at 20:04
2

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

Darrel Miller
  • 139,164
  • 32
  • 194
  • 243
  • 1
    Seroiusly? Your answer is "read the entire HTTP RFC"? It doesn't talk about REST or the standard conventions used today for implementing RESTful services. I wrote the web server I'm running on, so I know how HTTP works. I'm trying to use best practices when implementing a REST service running on that server. – ctacke Mar 15 '10 at 20:02
  • 1
    Nah, to understand how the HTTP methods work you only need to read the parts on the HTTP methods :-P. One of the REST constraints, Uniform Interface, basically implies that when doing REST over HTTP then RFC2616 is your bible. Maybe what you are looking for is the REST Cookbok which are a set of standard recipes for resolving common problems in RESTful systems.http://www.amazon.com/RESTful-Web-Services-Cookbook-Scalability/dp/0596801688/ref=sr_1_1?ie=UTF8&s=books&qid=1268695534&sr=8-1 – Darrel Miller Mar 15 '10 at 23:26
1

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.

Community
  • 1
  • 1
Herbert
  • 5,698
  • 2
  • 26
  • 34