PUT vs POST in REST

Question

According to the HTTP/1.1 Spec:

" The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line" i.e. Create.

" 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. If the Request-URI does not point to an existing resource, and that URI is capable of being defined as a new resource by the requesting user agent, the origin server can create the resource with that URI." That is, a Create or an Update.

So, which one should be used to Create resource, or one need to support both?

Answer 1

Use POST to create, and PUT to update. That's how Rails is doing it, anyway.

Answer 2

Overall:

Both PUT and POST can be used for creating.

You have to ask "what are you performing the action to?" though to distinguish what you should be using. If you want to use POST then you would do that to a list of questions. If you want to use PUT then you would do that to a particular question.

Great both can be used, so which one should I use in my RESTful design:

You do not need to support both PUT and POST.

Which is used is left up to you. But just remember to use the right one depending on what object you are referencing in the request.

Some considerations:

• Do you name your URL objects you create explicitly, or let the server decide? If you name them then use PUT. If you let the server decide then use POST.
• PUT is idempotent, so if you PUT an object twice, it has no effect. This is a nice property, so I would use PUT when possible.
• You can update or create a resource with PUT with the same object URL
• With POST you can have 2 requests coming in at the same time making modifications to a URL, and they may update different parts of the object.

An example:

I wrote the following as part of another answer on SO regarding this:

POST:

Used to modify and update a resource

POST /questions/<existing_question>

HTTP/1.1 Host: wahteverblahblah.com

Note that the following is an error:

POST /questions/<new_question> HTTP/1.1
Host: wahteverblahblah.com

If the URL is not yet created, you should not be using POST to create it while specyfing the name. This should result in a resource not found error because does not exist yet. You should PUT the resource on the server first.

You could though do something like this to create a resources using POST:

POST /questions HTTP/1.1
Host: wahteverblahblah.com

Note that in this case the resource name is not specified, the new objects URL path would be returned to you.

PUT:

Used to create a resource, or overwrite it. While you specify the resources new URL.

For a new resource:

PUT /questions/<new_question> HTTP/1.1
Host: wahteverblahblah.com

To overwrite an existing resource:

PUT /questions/<existing_question> HTTP/1.1
Host: wahteverblahblah.com

Answer 3

For both (create and update) I would use POST since you are changing something in the data store (they are not idempotent function calls). For me this link was very helpful: Form methods

Answer 4

REST is a very high-level concept. In fact, it doesn't even mention HTTP at all!

If you have any doubts about how to implement REST in HTTP, you can always take a look at the Atom Publication Protocol (AtomPub) specification. AtomPub is a standard for writing RESTful webservices with HTTP that was developed by many HTTP and REST luminaries, with some input from Roy Fielding, the inventor of REST and (co-)inventor of HTTP himself.

In fact, you might even be able to use AtomPub directly. While it came out of the blogging community, it is in no way restricted to blogging: it is a generic protocol for RESTfully interacting with arbitrary (nested) collections of arbitrary resources via HTTP. If you can represent your application as a nested collection of resources, then you can just use AtomPub and not worry about whether to use PUT or POST, what HTTP Status Codes to return and all those details.

This is what AtomPub has to say about resource creation:

To add members to a Collection, clients send POST requests to the URI of the Collection.

Answer 5

POST creates a child resource, so POST to /items creates a resources that lives under the /items resource. Eg. /items/1

PUT is for creating or updating something with a known URL.

Therefore PUT is only a candidate for CREATE where you already know the url before the resource is created. Eg. /blogs/nigel/entry/when_to_use_post_vs_put as the title is used as the resource key

Answer 6

You can find assertions on the web that say

• POST should be used to create a resource, and PUT should be used to modify one
• PUT should be used to create a resource, and POST should be used to modify one

Neither is quite right.

---

Better is to choose between PUT and POST based on idempotence of the action.

PUT implies putting a resource - completely replacing whatever is available at the given URL with a different thing. By definition, a PUT is idempotent. Do it as many times as you like, and the result is the same. x=5 is idempotent. You can PUT a resource whether it previously exists, or not (eg, to Create, or to Update)!

POST updates a resource, adds a subsidiary resource, or causes a change. A POST is not idempotent, in the way that x++ is not idempotent.

---

By this argument, PUT is for creating when you know the URL of the thing you will create. POST can be used to create when you know the URL of the "factory" or manager for the category of things you want to create.

so:

POST /expense-report

or:

PUT /expense-report/10929