What is the difference between POST and PUT in HTTP?

Overall:

Both PUT and POST can be used for creating.

You have to ask, "what are you performing the action upon?", to distinguish what you should be using. Let's assume you're designing an API for asking questions. 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 you use is 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 the 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 defined to assume idempotency, so if you PUT an object twice, it should have no additional effect. This is a nice property, so I would use PUT when possible. Just make sure that the PUT-idempotency actually is implemented correctly in the server.
• 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: www.example.com/

Note that the following is an error:

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

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

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

POST /questions HTTP/1.1
Host: www.example.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: www.example.com/

To overwrite an existing resource:

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

Additionally, and a bit more concisely, RFC 7231 Section 4.3.4 PUT states (emphasis added),

4.3.4. PUT

The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload.

I'd like to add my "pragmatic" advice. Use PUT when you know the "id" by which the object you are saving can be retrieved. Using PUT won't work too well if you need, say, a database generated id to be returned for you to do future lookups or updates.

So: To save an existing user, or one where the client generates the id and it's been verified that the id is unique:

PUT /user/12345 HTTP/1.1  <-- create the user providing the id 12345
Host: mydomain.example

GET /user/12345 HTTP/1.1  <-- return that user
Host: mydomain.example

Otherwise, use POST to initially create the object, and PUT to update the object:

POST /user HTTP/1.1   <--- create the user, server returns 12345
Host: mydomain.example

PUT /user/12345 HTTP/1.1  <--- update the user
Host: mydomain.example

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

PUT    /items/1      #=> update
POST   /items        #=> create

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 (section 9.2):

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

Short Answer:

Simple rule of thumb: Use POST to create, use PUT to update.

Long Answer:

POST:

• POST is used to send data to server.
• Useful when the resource's URL is unknown

PUT:

• PUT is used to transfer state to the server
• Useful when a resource's URL is known

Longer Answer:

To understand it we need to question why PUT was required, what were the problems PUT was trying to solve that POST couldn't.

From a REST architecture's point of view there is none that matters. We could have lived without PUT as well. But from a client developer's point of view it made his/her life a lot simpler.

Prior to PUT, clients couldn't directly know the URL that the server generated or if all it had generated any or whether the data to be sent to the server is already updated or not. PUT relieved the developer of all these headaches. PUT is idempotent, PUT handles race conditions, and PUT lets the client choose the URL.

In addition to differences suggested by others, I want to add one more.

In POST method you can send body params in form-data

In PUT method you have to send body params in x-www-form-urlencoded

Header Content-Type:application/x-www-form-urlencoded

According to this, you cannot send files or multipart data in the PUT method

EDIT

The content type "application/x-www-form-urlencoded" is inefficient for sending large quantities of binary data or text containing non-ASCII characters. The content type "multipart/form-data" should be used for submitting forms that contain files, non-ASCII data, and binary data.

Which means if you have to submit

files, non-ASCII data, and binary data

you should use POST method

To me, the key of understanding the difference was to understand who defines the ID of the resource:

Example (with some address service)

POST (sever creates new resource)

client               server/addresses      // NOTE: no ID in the request
  |                                 |
  | --{POST address data}-->        |
  |                                 |
  | <--{201, created addresses/321} |      // NOTE: resource ID in the reply
  |                                 |

PUT (sever sets data of resource, creating it if necessary)

client               server/addresses/321      // NOTE: *you* put the ID here!
  |                                 |
  | --{PUT address data (to 321)}-->|
  |                                 |
  | <--{201, created }              |          // NOTE: resource ID not required here
  |                                 |

There are many great answers with great details below, but that helped me to get to the point.

Summary

• Use PUT to create or replace the state of the target resource with the state defined by the representation enclosed in the request. That standardized intended effect is idempotent so it informs intermediaries that they can repeat a request in case of communication failure.
• Use POST otherwise (including to create or replace the state of a resource other than the target resource). Its intended effect is not standardized so intermediaries cannot rely on any universal property.

References

The latest authoritative description of the semantic difference between the POST and PUT request methods is given in RFC 7231 (Roy Fielding, Julian Reschke, 2014):

The fundamental difference between the POST and PUT methods is highlighted by the different intent for the enclosed representation. The target resource in a POST request is intended to handle the enclosed representation according to the resource's own semantics, whereas the enclosed representation in a PUT request is defined as replacing the state of the target resource. Hence, the intent of PUT is idempotent and visible to intermediaries, even though the exact effect is only known by the origin server.

In other words, the intended effect of PUT is standardized (create or replace the state of the target resource with the state defined by the representation enclosed in the request) and so is common to all target resources, while the intended effect of POST is not standardized and so is specific to each target resource. Thus POST can be used for anything, including for achieving the intended effects of PUT and other request methods (GET, HEAD, DELETE, CONNECT, OPTIONS, and TRACE).

But it is recommended to always use the more specialized request method rather than POST when applicable because it provides more information to intermediaries for automating information retrieval (since GET, HEAD, OPTIONS, and TRACE are defined as safe), handling communication failure (since GET, HEAD, PUT, DELETE, OPTIONS, and TRACE are defined as idempotent), and optimizing cache performance (since GET and HEAD are defined as cacheable), as explained in It Is Okay to Use POST (Roy Fielding, 2009):

POST only becomes an issue when it is used in a situation for which some other method is ideally suited: e.g., retrieval of information that should be a representation of some resource (GET), complete replacement of a representation (PUT), or any of the other standardized methods that tell intermediaries something more valuable than “this may change something.” The other methods are more valuable to intermediaries because they say something about how failures can be automatically handled and how intermediate caches can optimize their behavior. POST does not have those characteristics, but that doesn’t mean we can live without it. POST serves many useful purposes in HTTP, including the general purpose of “this action isn’t worth standardizing.”

I think there is also an interesting point that was not shared on this PUT vs POST question:

If you want to have a web application that works without JavaScript (for example if someone is using a command-line browser like Lynx or a browser addon like NoScript or uMatrix), you will have to use POST to send data since HTML forms only support GET and POST HTTP requests.

Basically if you want to use progressive enhancement (https://en.wikipedia.org/wiki/Progressive_enhancement) to make your web application work everywhere, with and without JavaScript, you cannot use other HTTP methods like PUT or DELETE, which were only added in HTTP version 1.1.

All the answers above and below are correct, just a small (important) note. All these "verbs" are recommendations and their effect is not enforced. The server is free to do whatever they want and this means writing with GET or whatever the server wants. It all depends on the implementation backend.

PHP for example, reads $_POST and $_GET. It's entirely up to the programmer what exactly it will be done by reading variables from these arrays.

So, which one should be used to create a resource? Or one needs to support both?

You should use PATCH. You PATCH the list of questions like

PATCH /questions HTTP/1.1

with a list containing your to be created object like

[
    {
        "title": "I said semantics!",
        "content": "Is this serious?",
        "answer": "Not really"
    }
]

It's a PATCH request as

• you modify the existing list of resources without providing the whole new content
• you change the state of your new question from non-existing to existing without providing all the data (the server will most probably add an id).

A great advantage of this method is that you can create multiple entities using a single request, simply by providing them all in the list.

This is something PUT obviously can't. You could use POST for creating multiple entities as it's the kitchen sink of HTTP and can do basically everything.

A disadvantage is that probably nobody uses PATCH this way. I'm afraid, I just invented it, but I hope, I provided a good argumentation.

You could use CREATE instead, as custom HTTP verbs are allowed, it's just that they mayn't work with some tools.

Concerning semantics, CREATE is IMHO the only right choice, everything else is a square peg in a round hole. Unfortunately, all we have are round holes.

Addition to all answers above:

Most commonly used in professional practice,

• we use PUT over POST in CREATE operation. Why? because many here said also, responses are not cacheable while POST ones are (Require Content-Location and expiration).
• We use POST over PUT in UPDATE operation. Why? because it invalidates cached copies of the entire containing resource. which is helpful when updating resources.

POST is used to send data to a server.
PUT is used to deposit data into a resource on the server (e.g., a file).

I saw this in a footnote (page 55) from the book HTTP: The Definitive Guide.

In the simpliest explained way:

POST does what it says, POST means it's presenting a request for a new object creation. MDN referse to this as 'other side-effects', an example being incrementing indexes (What the word 'POST' implies).

PUT can be thought of as updating existing data objects, When people are saying it can be used for adding items. This is because it can update child null values from an existing parent object.

MDN Method PUT Documentation

From the looks of it, both POST and PUT are same. However, they have some differences.

In HTTP Essentials: Protocols for Secure, Scaleable Web Sites, the author says:

The difference between POST and PUT is in how the server interprets the Uniform Resource Identifier. With a POST , the uri identifies an object on the server that can process the included data. With a PUT , on the other hand, the uri identifies an object in which the server should place the data. While a POST uri generally indicates a program or script, the PUT uri is usually the path and name for a file.

The author suggests that we use PUT to upload files, not POST. POST is for submitting forms.

Implemented correctly, the GET, HEAD, PUT, and DELETE method are idempotent, but not the POST method. So, when you make two PUT - you get the one new record, when you do two POSTs - you get two new records.

However, please note that, HTML forms only support GET and POST as HTTP request methods.

<form method="put"> is invalid HTML and will be treated like , i.e. send a GET request.