6202

Background Information Analysis:

According to RFC 2616, § 9.5, POST is used to create a resource:

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.

According to RFC 2616, § 9.6, PUT is used to create or replace a resource:

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.

My Question:

So, which HTTP method should be used to create a resource? Or should both be supported?

13
  • 66
    It may be helpful to use the definitions in HTTPbis - Roy put a fair amount of work into clarifying them. See: tools.ietf.org/html/… Oct 23, 2011 at 21:03
  • 19
    Just to bring @MarkNottingham's comment to the latest revision, here's POST and PUT, as defined on HTTPbis. Nov 18, 2012 at 1:58
  • 46
    It seems to me that this debate has arisen from the common practice of oversimplifying REST by describing the HTTP Methods in terms of CRUD operations.
    – Stuporman
    Feb 14, 2013 at 17:05
  • 7
    Unfortunally the first answers are wrong about POST. Check my answer for a better explanation of the differences: stackoverflow.com/a/18243587/2458234
    – 7hi4g0
    Nov 25, 2013 at 5:21
  • 33
    PUT and POST are both unsafe methods. However, PUT is idempotent, while POST is not. - See more at: restcookbook.com/HTTP%20Methods/put-vs-post/… Jan 10, 2014 at 20:26

41 Answers 41

1
2
10

While there is probably an agnostic way to describe these, it does seem to be conflicting with various statements from answers to websites.

Let's be very clear and direct here. If you are a .NET developer working with Web API, the facts are (from the Microsoft API documentation), http://www.asp.net/web-api/overview/creating-web-apis/creating-a-web-api-that-supports-crud-operations:

1. PUT = UPDATE (/api/products/id)
2. MCSD Exams 2014 -  UPDATE = PUT, there are **NO** multiple answers for that question period.

Sure you "can" use "POST" to update, but just follow the conventions laid out for you with your given framework. In my case it is .NET / Web API, so PUT is for UPDATE there is no debate.

I hope this helps any Microsoft developers that read all comments with Amazon and Sun/Java website links.

8

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.

7

In practice, POST works well for creating resources. The URL of the newly created resource should be returned in the Location response header. PUT should be used for updating a resource completely. Please understand that these are the best practices when designing a RESTful API. HTTP specification as such does not restrict using PUT/POST with a few restrictions for creating/updating resources. Take a look at http://techoctave.com/c7/posts/71-twitter-rest-api-dissected that summarizes the best practices.

1
  • For the most part, from reading through all this noise, you seem on the ball. I would say though, we should refer to PUT as the replace method, rather than the create/update. I think it better describes in one what it does.
    – thecoshman
    Jun 8, 2015 at 8:15
6

POST: Use it for creating new resources. It's like INSERT (SQL statement) with an auto-incremented ID. In the response part it contains a new generated Id.

POST is also used for updating a record.

PUT: Use it for creating a new resource, but here I know the identity key. It's like INSERT (SQL statement) where I know in advance the identity key. In the response part it sends nothing.

PUT is also used for updating a resource

1
  • 6
    PUT is not for update, it is for replace, note that to create you are replacing nothing with something. POST is absolutely not for update in any shape of form.
    – thecoshman
    Jun 8, 2015 at 8:11
4

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.

4

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.

3

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.

4
  • I think you should be careful in stating that PATCH should be used without providing some clarifying statements. PATCH is great for updating resources, but it's not meant for creating resources. The HTTP specs specifically call out that it is only for updating resources. You can make anything work as you've stated, but the verbs lose their meaning when you arbitrarily give them non-standard functionality.
    – Jitsusama
    Jul 2, 2019 at 14:01
  • @Jitsusama Read my last but one sentence.... and maybe google for this "It’s like trying to hack a programming paradigm out of the TCP packet header control bits! If URG is high then my calendar appointment is very important. If ACK is low, then I’m denying your friend request.".
    – maaartinus
    Jul 3, 2019 at 0:03
  • I think this is not a good idea. Basically, if you say inserting into a list is a patch, everything becomes a patch: inserting, updating, even deleting. This does not solve the problem but actually adds another ambiguity.
    – dariok
    Oct 25, 2019 at 18:18
  • @dariok Agreed, it'd make it even a bit worse than it already is.
    – maaartinus
    Oct 25, 2019 at 22:51
3

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.
2

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

2
  • 1
    The reason this is all a tad confusing is because the word POST doesn't say or even suggest any clear meaning - certainly nothing about being "NEW". So I'm mystified by your first sentence telling us the word POST does what it says
    – PandaWood
    Jun 28, 2022 at 6:47
  • What trips people up is Putting something can imply Posting (but not the converse). As a noun it doesn't make sense, but only in the verb tense it does. Thinking of when putting the method into an html form, you have to add an Action and Method (both do things and are verbs). The action of placing a post-it on a board, to Post It means you're placing something new there and not editing an existing one. I can relate, even b.i.t.d JavaScript was confusing Juniors with Java because poor word choice when it came out. It's rare when a word in programming is not implicit lol. Jul 15, 2022 at 19:46
1

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.

0

POST vs PUT

Let's get the facts on POST and PUT according to the Internet Engineering Task Force (IETF):

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.

Proper interpretation of a PUT request presumes that the user agent knows which target resource is desired. A service that selects a proper URI on behalf of the client, after receiving a state-changing request, SHOULD be implemented using the POST method rather than PUT.

https://www.rfc-editor.org/rfc/rfc7231#section-4.3.4

Based on the above, POST should be used to do MOST (if not all) of your CREATE or ALTER data routines on the server. Only POST is supported in HTML form field methods for this very reason, while PUT and DELETE are not supported in HTML forms (see below).

PUT acts as a sub-type of the POST method as it can do only one narrow range of actions that POST does. Both POST and PUT can create and change data. The different is "intent". POST has no intention other than to work with the server's various ways of creating or altering the state of data. PUT has one intent...to REPLACE the state of ONE RESOURCE on the server with its own (which POST can also do, btw, and does often online).

Because of heavy use of JavaScript the past decade and XMLHttpRequest calls, this has opened the door up to websites using PUT and DELETE more often. WebAPI's are now configured to apply Http Method PUT and the rules to use it more consistently in 2023, than in the past. So the question has been raised, why use it, when we have been using POST to do the same thing successfully the past 20+ years?

I would ONLY use PUT in one case...where you are using JavaScript to create or alter the identity of a "resource" (state of an item), know the resource identity in your PUT (most often a URI/URL), and the WebAPI endpoint on the server strictly honors change the resource state with the one sent in the PUT. This must be total and complete, unlike with a post.

In the case of PUT, a good way to enforce this, rather than rely on sketchy JavaScript rules, is to rely on a UNIQUE IDENTIFIER in the URL on the server. This prevents PUT coming in without any rules or identifier. An example might be: https://example.com/123, with "123" being the ID of some resource or data point at the WebAPI endpoint.

The URI in a POST request does not need to identify the resource that will handle the enclosed entity or its state or what is changed. In contrast, the URI in a PUT request identifies the entity enclosed with the request and what will be replaced with the data or state in a PUT request.

BROWSERS DO NOT SUPPORT "PUT" or "DELETE"!

Did you know that HTML Form method attributes in browsers the past 20+ years have only supported POST and GET, and do not support PUT?

POST and GET work ok...
<form id="form1" name="form1" method="get" action="/form">...</form>
<form id="form2" name="form2" method="post" action="/form">...</form>

PUT NOT SUPPORTED!
<form id="form3" name="form3" method="put" action="/form">...</form>

DELETE NOT SUPPORTED!
<form id="form4" name="form4" method="delete" action="/form">...</form>

Crazy, huh?

When a browser user submits data to a server, nobody knows if they are creating, deleting, or modifying data. A POST can add or change an entity just like a PUT can, right? So, other than the identifying URL, the right action or HTTP Verb to use is most often POST. Therefore, PUT has always been optional in the traditional web world for decades.

When a form pushes data to the server, they are not honoring the HTTP VERBS as they were meant to be used. If you set up your server and HTML to follow conventions they would fail. AJAX or other JavaScript REST calls could override conventions and send a PUT meant for a POST for a given URL that is not an identifier type. But it would not matter today online.

To me, using PUT comes down to JavaScript use and the URI or Unique Identifier; the structure of the URL "posted" to the browser. The server then must look at the Http VERY bit also the URL to decide what the method is honored, then route the POST or PUT or DELETE etc. to the right place or process the resource changes as required. Only this then honors the Post vs Put design.

It's the flawed nature of today's client-side model with its broken HTML5 design, plus the corrupting nature of today's thick-client JavaScript API calls and other circus-tricks, that have polluted what should have been a very simple HTTP Standard created long ago by very forward looking people. But adding PUT to today's mix, and honoring its narrow use with scripting and unique identifiers will help to clean up the messy web we have today.

1
2

Not the answer you're looking for? Browse other questions tagged or ask your own question.