What is the difference between POST and PUT in HTTP?

Created 10.03.2009 14:25
Viewed 2.62M times
5678 votes

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.

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

19
Comments
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/… by Mark Nottingham, 23.10.2011 21:03
Just to bring @MarkNottingham's comment to the latest revision, here's POST and PUT, as defined on HTTPbis. by Marius Butuc, 18.11.2012 01:58
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. by Stuporman, 14.02.2013 17:05
Unfortunally the first answers are wrong about POST. Check my answer for a better explanation of the differences: stackoverflow.com/a/18243587/2458234 by 7hi4g0, 25.11.2013 05:21
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/… by Dinesh Saini, 10.01.2014 20:26
you know... I realise the spec refers to PUT as 'update', but I think everyone would be a lot less confused if we said it 'replaced', that is what it does after all. by thecoshman, 15.06.2014 20:28
In pratice, 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 techoctave.com/c7/posts/71-twitter-rest-api-dissected that summarizes the best practices. by java_geek, 06.10.2014 06:42
idempotency is the key. Read PUT or POST: The REST of the Story by John Calcote. If your method is idempotent, go with PUT. If not go with POST. by LCJ, 11.08.2016 18:12
I don't understand the prevailing wisdom on this. OP's citation for PUT begins with "The PUT method requests that the enclosed entity be stored...." That screams "creation" to me. When we talk about "putting" something somewhere, we're talking about a place it hadn't been previously. You don't "put" something to change it. When you amend a document, you don't "put" a new one. The use of the HTTP verb PUT to mean "update" is an ill semantic fit. by Keith Tyler, 28.03.2017 16:31
PUT began as a way for early Microsoft HTML design tools to publish content directly to a server. The fact that it was also used to update (wholesale) was due to the lack of another updating method. Even still since it was a wholesale update, it really was creation, just one that was idempotent. An "update" implies that some aspect of the previous state was maintained. by Keith Tyler, 28.03.2017 16:33
Real world scenario in elastic documentation: elastic.co/guide/en/elasticsearch/reference/current/…. Have a look at difference between all PUT requests and last POST request example. by DevDio, 10.04.2018 09:02
The JavaBrains explains it very clealy. Have a look youtube.com/watch?v=rhTkRK53XdQ by Ram, 17.08.2018 15:32
Difference between POST vs PUT methods should be described in defined context. Such as here, question is about REST, and it is actually about consistency and uniform interface. Till the time, you are honoring the API design consistency, you are good. by lokesh, 17.08.2018 18:22
Note that if you want to make a web application work even if JavaScript is disabled, you should use POST: stackoverflow.com/questions/630453/put-vs-post-in-rest/… by baptx, 26.06.2019 09:30
OP's enclosed quote about POST is no longer valid. "The actual function performed by the POST method is determined by the server and is usually dependent on the effective request URI. The action performed by the POST method might not result in a resource that can be identified by a URI. " via tools.ietf.org/html/… by sindhu_sp, 13.11.2019 10:09
You can use both. POST is used if the server decides the new URI of the resource, PUT is used if the client decides it. See: mscharhag.com/api-design/http-post-put-patch by micha, 21.02.2020 08:42
Generally, in practice, always use PUT for UPDATE operations. Always use POST for CREATE operations. see this by majurageerthan, 29.06.2020 05:22
The idempotency is important. But, to be idempotent, you must have a unique key (or set of keys). If the unique key is specified in a POST call twice, the second should generate an error. In a PUT call, it should create/update/replace the resource. It is possible to have a POST call and not provide a unique key (it just creates a new resource each time). However, it is not possible to do PUT call without a key. by rfportilla, 28.10.2020 12:51
All this talk about PUT being idempotent, and POST isn't, are ignoring the elephant in the room. The browser will retry either of them, even POST, if the connection is closed by the server, so you need to develop your API to be idempotent regardless, so when it happens to you, you can't complain! :) The choice of method is almost moot. stackoverflow.com/questions/15155014/… w3.org/Protocols/rfc2616/rfc2616-sec8.html#sec8.2.4 by Tony B, 07.11.2020 20:14
Show remaining 14 comments
Answers 35
41
4468

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.

10.03.2009 14:29
Comments
I think one cannot stress enough the fact that PUT is idempotent: if the network is botched and the client is not sure whether his request made it through, it can just send it a second (or 100th) time, and it is guaranteed by the HTTP spec that this has exactly the same effect as sending once. by Jörg W Mittag, 10.03.2009 15:17
@Jörg W Mittag: Not necessary. The second time could return 409 Conflict or something if the request has been modified in meantime (by some other user or the first request itself, which got through). by Mitar, 27.11.2011 23:28
I think there is no difference in definition. 409 Conflict could be a result even for the first request the client made. In any case it should investigate the problem. by Mitar, 28.11.2011 02:21
If I'm not mistaken, what we should be stressing is that PUT is defined to be idempotent. You still have to write your server in such a way that PUT behaves correctly, yes? Perhaps it's better to say "PUT causes the transport to assume idempotence, which may affect behavior of the transport, e.g. caching." by Ian Ni-Lewis, 28.12.2011 02:05
There are some ideas about how to make POST more reliable on Paul Prescod's website, though the site overall doesn't seem to be kept up to date. by hotshot309, 04.04.2012 18:48
To make things even clearer it might be an idea to add that this example should return an error: PUT /questions HTTP/1.1 Host: wahteverblahblah.com by Martin Brown, 04.10.2013 08:46
I second that, @MartinBrown... your point is quite illuminating for me, actually. The answer as it stands is already fantastic, though, don't get me wrong! by Eric Fuller, 23.10.2013 03:57
@JörgWMittag Idempotence catchphrase? How about "Send and send and send my friend, it makes no difference in the end." by James Beninger, 03.03.2014 17:13
PUT should only be used to create a resource if the client cares about the resource's name. A client caring about a resource's name indicates coupling. Coupling is the result of poor practices. Therefore, use POST. If there is concern about a resource being created twice with POST (since it's not idempotent) read this answer. by Joshcodes, 17.03.2014 19:00
@JörgWMittag If a PUT is idempotent, what happens if the PUT is creating a new resource and the server is the one generating the object id? That would imply every PUT call would create a different object id. Does that mean that a PUT should not/cannot be used in that case, and a POST is required instead? by Eric B., 09.07.2014 04:37
@EricB. The "object ID" is what he is referring to as the name. Thus, it should be supplied as part of the URL when using POST and not be generated by the server. by Legogris, 22.09.2014 07:28
In pratice, 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 by java_geek, 06.10.2014 06:28
One note on using POST for CRUD style updates: I know that Roy Fielding pointed out that it should be more important for a RESTful design to make use of Hypermedia and discoverable self-explaining APIs than (e.g.) disallowing POST requests to perform item updates. But the quoted http spec gives a rule of thumb: In general it is quite intuitive and consistent to allow POST only for creating new subordinates for the given resource. For replacing or updating existing resources, I always prefer PUT or PATCH. by matthias, 12.03.2015 18:01
Whatever the semantic value of POST vs PUT: If you have to support IE9 and IE8, beware that CORS requests in these versions do not support PUT - only GET/POST. See blogs.msdn.com/b/ieinternals/archive/2010/05/13/… by flexponsive, 10.04.2015 19:21
Can someone elaborate on this sentence. "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." Please explain why this applies to POST and not to PUT? by Kevin Wheeler, 08.09.2015 22:28
@KevinWheeler: Bill de Hora has a good blog post about using POST to update only some fields of a resource, while PUT must supply all fields (whether creating or updating): dehora.net/journal/2009/02/03/just-use-post He makes the point that PUT can be very heavy weight if you have to send through all the fields when you only want to update one. So, following his scheme, you could have POST sending through an update to a couple of fields and another POST request updating another couple of fields in the same resource. Not sure but I think PATCH now does the same sort of thing. by Simon Tewsi, 13.01.2016 21:31
Thinks of them as: PUT = insert or update; POST = insert. So when you make two PUT - you get the one new record, when you do two POSTs - you get two new records. by Eugen Konkov, 22.08.2016 09:34
"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." .......... you mean POST can update? by Raúl, 11.11.2016 07:03
"Used to modify and update a resource" ....... you must meant 'or' here - right ? by Raúl, 11.11.2016 07:04
@Learner I second your sentiment. This answer and the examples are confusing. Words are used inconsistently. by lucid_dreamer, 18.06.2017 01:52
Think like a server: Expect an item to be uniquely identifiable. If I receive a PUT without an identifier I'm going to reject it because it's not telling me what to update. If I receive a POST with an identifier I'm going to reject it because I can't create what already exists. by Brian Lowe, 20.07.2017 13:16
Assuming I having the following URL: test.awesome.com/questions, is the above saying that I would PUT to that URL to create a new resource? I thought it's POST to a collection and PUT to a URL with a specified ID. Isn't it PUT here: test.awesome.com/questions/1 and POST here: test.awesome.com/questions? Or, is it saying if test.awesome.com/questions/1 doesn't exist, PUT will create it or replace it if it already exists on the server? by cr1pto, 22.09.2017 16:11
Does idempotency of PUT mean we cannot have the same resource name or that objects that have the same hashes cannot exist at the same time ? by monolith, 21.11.2017 19:56
@wedran idempotency means, that if someone calls PUT once or multiple times, the outcome is still the same. So an operation, where every call causes a change (e.g. a counter to increment) wouldn't be idempotent ( restapitutorial.com/lessons/idempotency.html ). I would recommend reading through all answers answers here to get a better understanding. It doesn't have anything to do with the resource name or a hash. by skofgar, 21.11.2017 23:02
Am I mistaken, or does this answer contradict the info in the question? There it says Post=Create. Put=Update if possible. If not, create. However here, it says 'Post=Update'. I'm confused. by Mark A. Donohoe, 15.12.2017 21:43
You should really be using PATCH to update a entity, PUT to insert a entity , DELETE to delete/remove a entity and a POST to do other things, like submitting form data type requests. by SynackSA, 19.01.2018 19:03
Would be nice if we could add the difference with PATCH. Right now I'm in a situation where I define the resource's ID beforehand (not the server), I'm therefore using PUT to create it, and then POST to update it, but I could also use PATCH instead of POST and that would make more sense, semantically speaking. by Vadorequest, 20.02.2018 00:49
@BrianR.Bondy you Wrote: POST: Used to modify and update a resource POST /questions/<existing_question> HTTP/1.1. But in this case you make POST method idempotent. This is in contrast with HTTP specification! RFC 7231 by Glauco Cucchiar, 02.03.2018 10:50
@BrianR.Bondy in the below link definitions are contradictory restfulapi.net/rest-put-vs-post by User, 10.04.2018 12:00
@Sirius - I thought the same thing, but technically POST can be used to append to an existing resource as stated in Section 4.3.3 of RFC 7231 - 4th bullet point. I would consider appending as an update but it could be interpreted differently by commandt, 03.05.2018 18:36
"You do not need to support both PUT and POST," is followed by, "If the URL is not yet created, you should not be using POST to create it while specifying the name... You should PUT the <new_question> resource on the server first." Perhaps, "You do not need to support POST if you support PUT"? Or is @SynackSA on to something? by ruffin, 30.08.2018 14:05
does idempotent mean that if a ressource already exist and is similar the PUT method preserve some ressource by overcome the point and go directly to the next point ? A kind of optimize save in other word by Webwoman, 03.09.2018 00:44
Isn't author's claim that POST can be used to modify/update incorrect? For example he is using POST /questions/<existing_question> which means that the POST request is aware of the location of the resource which is <existing_question> but this means POST is showing idempotent behavior cause no matter how many time we make this request the same resource(<existing_question>) will be accessed at the server which is not correct as POST is supposed to be non-idempotent which means every time we invoke this it should change the state of the server. by Yug Singh, 30.09.2018 19:48
put "SHOULD be considered as a modified version" - it's allowable that PUT on an existing object not perform the update. but reccomended that it does by Jasen, 18.01.2019 01:57
for PUT instead of create I prefer to say 'associate or modifiy the existing' it is much accurate by user1438644, 17.04.2019 23:15
I think that the answer regarding POST is not correct. POST /questions/<existing_question> should never be used. Use POST /questions to create a new question without knowledge of the question id. Use PUT /questions/<questionId> to create (in case the client manages the question ids, else use POST) or replace (completely) a question knowing the question id. Use PATCH for partial modification. by Guillaume Vauvert, 17.07.2019 11:48
Just to put things into perspective on the big word idempotent. It just means, POST is like, myWallet.AddMoney(999) and PUT is myWallet.SetMoney(999). by BoBoDev, 06.08.2020 01:11
@EugenKonkov - So what happens when I use post to update an existing resource as mentioned in the answer ? Do we get back a new resource or do the updates get applied to the existing resource ? by MasterJoe, 10.09.2020 17:49
@JörgWMittag - Please see the comment by Eugen Konkov. Does that sound correct ? Here is the comment - Thinks of them as: PUT = insert or update; POST = insert. So when you make two PUT - you get the one new record, when you do two POSTs - you get two new records. by MasterJoe, 10.09.2020 17:50
@MasterJoe: indepondent means that despite on any requests you made you will get same result. For Our PUT. When you did one request - you get one record in database with your dara. When you did two requests - you get one record in database with your data. When you did N requests you get one record in database with your data. When you do POST request - after each request you will get new additional record in database with your (POSTed) data. by Eugen Konkov, 11.09.2020 06:32
@MasterJoe: No body does not restrict you to make POST requests to your site indepondent. This is up to your site API. This probably will be just a surprise for your users who does not read your API's documentation. by Eugen Konkov, 11.09.2020 06:39
Show remaining 36 comments
15
2319

You can find assertions on the web that say

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
22.04.2010 14:55
Comments
I agree, wherever idempotence is concerned it should trump any other concerns since getting that wrong can cause many many unexpected bugs. by Josh, 26.10.2010 05:56
Yes. In fact, AtomPub protocol defies this (or more accurately, restricts its semantic meaning of PUT): "PUT is used to edit a known Resource. It is not used for Resource creation." Just because AtomPub protocol says so (which is valid by the way) doesn't mean all RESTful protocols must follow it. (because REST is generic) by Hendy Irawan, 14.04.2011 16:04
If POST can update a resource, how is that not idempotent? If I change a students age using PUT and do that 10x times the students age is the same if I did it once. by Jack Ukleja, 06.05.2011 10:54
@Schneider, in this case your server is making an extra effort to guarantee idempotence, but it is not advertising it. Browsers will still warn the user if they try to reload such a POST request. by Tobu, 06.01.2012 10:53
@Schneider POST may create a subsidiary resource; hence you can POST to collection, like POST /expense-reports and it would create as many entities (expense reports) on your server as the quantity of requests you've sent, even if they are completely similar. Think of it as inserting the same row in the DB table (/expense-reports) with auto-incremented primary key. Data remains the same, key (URI in this case) is generated by server and is different for every other insert (request). So, POST effect can be idempotent, but also may not. Hence, POST is not idempotent. by Snifff, 26.01.2012 17:32
This is dead on, and the "accepted" answers look to me (@brian) to miss this critical subtlety. by Andrew Roberts, 21.03.2012 18:48
Let's say we have entities which may have two properties - name and date. If we have an entity with an existing name and date, but then make requests to it specifying only a name, the proper behavior of PUT would be to obliterate the date of the entity, whereas POST may update only the properties specified, leaving the unspecified properties as they were before the request was made. Does that sound correct/reasonable, or is it an improper use of PUT (I saw references to PATCH, which it seems would be more appropriate, but doesn't exist yet)? by Jon z, 08.05.2013 18:28
This is dead wrong. Idempotence should not decide if PUT or POST is used. Who owns the responsibility for the URL structure decides if PUT or POST is used. To understand how to handle duplicate POST requests see this answer. by Joshcodes, 24.04.2014 12:22
I wonder if what he means by "POST can update a resource" is that by POSTing to a collection you are adding an item to it and therefore "updating the collection". That distinction seems a bit misleading. I like the answer, though. by Thomas, 28.05.2015 13:43
Thank you, this is very helpful. To further your analogy, POST may be used to "assign" (as opposed to x++), but it's more like obj.setX(5) -- the setX method should result in x being 5, but may have side effects. by Nicole, 01.10.2015 22:21
If using POST to partially update an existing resource, such as updating only a couple of fields, can you specify the resource name? The reason I ask is that many people say POST can't be used with an individual resource, only with its parent collection. eg POST applied to expense reports. Is it possible to update say a single field of expense report 10929 using POST /expense-report/10929 ? by Simon Tewsi, 13.01.2016 21:39
I agree with this answer. Key difference is idempotency of PUT. I found a very good explanation of idempotency at stormpath.com/blog/put-or-post by Naymesh Mistry, 05.09.2016 02:01
Comparing PUT and POST to mysql: POST is like an INSERT INTO without providing the ID of an auto-increment column, if you do it multiple times, you will create multiple rows. PUT is like an UPDATE using the primary key in the WHERE statement, if you do it multiple times, the row should be the same after each one. Some vendors may also allow you to PUT to create, which would be like an INSERT INTO providing a value for the auto-increment column. by Jo., 16.03.2017 19:01
There is nothing that says you cannot implement POST to be idempotent, all the standard says is that it is treated as unsafe. Implenting an idempotent post for resource creation where the client can generate the id and pass along a request token to identify retries works well.. eg /api/foobars/{GUID}?request={AnotherGUID} by nrjohnstone, 20.08.2017 18:16
Helpful mnemonic: IdemPUTent by Mercury, 04.09.2019 07:38
Show remaining 10 comments
15
744
  • POST to a URL creates a child resource at a server defined URL.
  • PUT to a URL creates/replaces the resource in its entirety at the client defined URL.
  • PATCH to a URL updates part of the resource at that client defined URL.

The relevant specification for PUT and POST is RFC 2616 §9.5ff.

POST creates a child resource, so POST to /items creates a resources that lives under the /items resource. Eg. /items/1. Sending the same post packet twice will create two resources.

PUT is for creating or replacing a resource at a URL known by the client.

Therefore: PUT is only a candidate for CREATE where the client already knows 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

PUT replaces the resource at the known url if it already exists, so sending the same request twice has no effect. In other words, calls to PUT are idempotent.

The RFC reads like this:

The fundamental difference between the POST and PUT requests is reflected in the different meaning of the Request-URI. The URI in a POST request identifies the resource that will handle the enclosed entity. That resource might be a data-accepting process, a gateway to some other protocol, or a separate entity that accepts annotations. In contrast, the URI in a PUT request identifies the entity enclosed with the request -- the user agent knows what URI is intended and the server MUST NOT attempt to apply the request to some other resource. If the server desires that the request be applied to a different URI,

Note: PUT has mostly been used to update resources (by replacing them in their entireties), but recently there is movement towards using PATCH for updating existing resources, as PUT specifies that it replaces the whole resource. RFC 5789.

Update 2018: There is a case that can be made to avoid PUT. See "REST without PUT"

With “REST without PUT” technique, the idea is that consumers are forced to post new 'nounified' request resources. As discussed earlier, changing a customer’s mailing address is a POST to a new “ChangeOfAddress” resource, not a PUT of a “Customer” resource with a different mailing address field value.

taken from REST API Design - Resource Modeling by Prakash Subramaniam of Thoughtworks

This forces the API to avoid state transition problems with multiple clients updating a single resource, and matches more nicely with event sourcing and CQRS. When the work is done asynchronously, POSTing the transformation and waiting for it to be applied seems appropriate.

07.04.2010 05:52
Comments
Or from the other side of the fence: PUT if the client determines the resulting resource's address, POST if the server does it. by DanMan, 28.11.2012 19:47
I think that this answer should be edited to make it more clear what @DanMan pointed in a very simple way. What I find the most valuable here is the note at the end, stating that a PUT should be used only for replacing the whole resource. by Hermes, 26.11.2013 22:37
PATCH isn't a realistic option for at least a few years, but I agree with the ideology. by crush, 03.10.2014 17:33
I'm trying to understand, but using PUT to create something would only make sense if the client knows for sure that the resource doesn't exist yet, right? Following the blog example, say you have created hundreds of blog posts in a couple of years, then accidentally pick the same title as you did for a post two years ago. Now you have gone and replaced that post, which wasn't intended. So using PUT to create would require the client to track what is taken and what is not, and could lead to accidents and unintended side effects, as well as having routes that do two entirely different things? by galaxyAbstractor, 30.01.2015 09:01
You are correct. PUTting a blog post at the same url as an existing one would cause an update to that existing post (although you could obviously check first with a GET). This indicates why it would be a bad idea to use just the title as the URL. It would however work anywhere there was a natural key in the data... which in my experience is rare. Or if you used GUIDs by Nigel Thorne, 03.02.2015 05:20
@crush: Why isn't PATCH a realistic option for at least a few years? by arthropod, 21.06.2016 03:58
@NigelThorne The only answer that talks about server defined and client defined URLs. Who does validation on client defined URLs? by realPK, 26.07.2016 22:17
@PK_ the server validates the URL. The client would have to adhere to the url schema the server supports. Invalid urls would be rejected by the server. by Nigel Thorne, 30.08.2016 06:44
I'm working on a project where the id's are known to the client. So I'd like to use PUT for creation. However, a colleague disagrees with the argument that it would be confusing if the resource would get deleted while someone else does a PUT (to update as a whole), now the resource would be recreated, even though it was deleted. His point is, that in a POST, PUT, DELETE scenario PUT should return a 404 if someone wants to update a resource and it doesn't exist. Any thoughts that might help? by skofgar, 21.11.2017 23:15
HTTP says ... when a client 'puts' to a url, it is requesting that url to hold that data. It's up to the server to decide if it's happy to do that. If you want 'DELETE' to stop PUTs working... then that's fine, but can you ever have anything at that url ever again? If so, then you should probably let the subsequent PUT through... after all one of your users is trying to put content at that location for a reason. Who's to say who was more correct? :) the answer is.. "your domain". Do what models your domain. but PUT means "I am trying to store this here". by Nigel Thorne, 22.11.2017 06:47
@skofgar PUT is supposed to be idempotent (multiple identical requests have the same result.) That's a powerful concept and makes developers' lives infinitely easier because it's a reliable operation. I agree w/ the user confusion in that scenario, but I think you want to address that in the front end as much as possible. It's also not uncommon behavior and is sometimes very helpful (e.g. if editing in one browser tab, and you delete it in another by mistake, then saving restores the resource in its entirety) by John Neuhaus, 14.05.2018 15:41
@skofgar In your scenario (clients know the ids and drive the creation). What about PUT to create and PATCH to partially update? You save some bandwidth and PATCH could fail if the resource is deleted. by Marcel Toth, 06.02.2020 00:56
Good idea, I haven't seen PATCH being used very widely, furthermore I want to keep the API's as simple as possible. But I think using PATCH would have made sense in this case. by skofgar, 08.02.2020 16:23
I was going to use PUT to edit profile but after reading the article and talking with the client, he told he only wanted users to edit specific parts of profile and I consider that to be a perfect application for /changeAddress of something as mentioned in the blog post as it puts the server back in control. And removes the state from the client. Not to mention that I can now record stuff like how often do users edit their profile and what do they change by Hemil, 24.07.2020 10:27
I think this should be the answer because it's the most clear for me. by Huan, 13.02.2021 13:26
Show remaining 10 comments
15
242

Summary:

Create:

Can be performed with both PUT or POST in the following way:

PUT

Creates THE new resource with newResourceId as the identifier, under the /resources URI, or collection.

PUT /resources/<newResourceId> HTTP/1.1 

POST

Creates A new resource under the /resources URI, or collection. Usually the identifier is returned by the server.

POST /resources HTTP/1.1

Update:

Can only be performed with PUT in the following way:

PUT

Updates the resource with existingResourceId as the identifier, under the /resources URI, or collection.

PUT /resources/<existingResourceId> HTTP/1.1

Explanation:

When dealing with REST and URI as general, you have generic on the left and specific on the right. The generics are usually called collections and the more specific items can be called resource. Note that a resource can contain a collection.

Examples:

<-- generic -- specific -->

URI: website.com/users/john
website.com  - whole site
users        - collection of users
john         - item of the collection, or a resource

URI:website.com/users/john/posts/23
website.com  - whole site
users        - collection of users
john         - item of the collection, or a resource
posts        - collection of posts from john
23           - post from john with identifier 23, also a resource

When you use POST you are always refering to a collection, so whenever you say:

POST /users HTTP/1.1

you are posting a new user to the users collection.

If you go on and try something like this:

POST /users/john HTTP/1.1

it will work, but semantically you are saying that you want to add a resource to the john collection under the users collection.

Once you are using PUT you are refering to a resource or single item, possibly inside a collection. So when you say:

PUT /users/john HTTP/1.1

you are telling to the server update, or create if it doesn't exist, the john resource under the users collection.

Spec:

Let me highlight some important parts of the spec:

POST

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

Hence, creates a new resource on a collection.

PUT

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

Hence, create or update based on existence of the resource.

Reference:

14.08.2013 22:47
Comments
This post was helpful to me in understanding that POST adds "something" as a child to the given collection (URI), whereas PUT explicitly defines the "something" at the given URI location. by kwah, 23.11.2013 16:33
It is a very reasonable way to implement a CRUD API that is REST/http complient. A good reading: the RFC about HTTP, and in particular what is idempotent and the expected behavior of web cache. The use of POST/PUT are constrained by the expected behavior of cache (web or user agent) by mcoolive, 21.10.2014 09:34
This is the best answer, here, I think: none of this "POST can update a resource" nonsense. I like your statement, "Update can only be performed with PUT". by Thomas, 28.05.2015 13:44
No, PUT is not for update or create. It is for replacing. Note that you can replace nothing with something for the effect of creating. by thecoshman, 08.06.2015 08:07
@thecoshman I have posted in my answer the relevant parts of the HTTP/1.1 spec. Read the last part of my answer entitled Spec. The spec clearly states that PUT is used to create or update an entity. by 7hi4g0, 08.06.2015 12:50
@7hi4g0 PUT is for for updating with a complete replacement, in other words, it replaces. You replace nothing with something, or something with a completely new something. PUT is not for making a minor change (unless you have the client make that minor change and provide the entire new version, even what is remaining the same). For partial modification, PATCH is the method of choice. by thecoshman, 08.06.2015 12:57
@thecoshman I never said that PUT should be used for partial modification. If you don't like the terminology, I can restate. The spec clearly states that PUT is used to create or modify an entity. by 7hi4g0, 08.06.2015 13:07
@thecoshman I guess you can say, create or replace, but the two are different actions according to the Spec. Either way, update, modify, replace are only terms. by 7hi4g0, 08.06.2015 13:15
@7hi4g0 my point is, if you read the rest of that sentence from the spec, you are updating that URI to have a completely new resource at that location. As such, it is replace 100% with what data is included in this PUT request. Likewise, I'd argue that create is effectively just replacing 'nothing with something'. And so, you can "Keep It Simple Stupid" by just saying "PUT is for replacing". by thecoshman, 09.06.2015 16:15
@thecoshman You could, but it wouldn't be too clear that create is also covered in there. In this case, it is better to be explicit. by 7hi4g0, 09.06.2015 20:21
@7hi4g0 I would generally say that POST is (usually) more appropriate for create, but still. I think we can leave it at that, we've at least given people sensible discussion to think about, which IMO is the most important thing to have when you have fluffy 'guideline' :P by thecoshman, 09.06.2015 21:37
PUT can be used to create a resource and is appropriate for creating resources if the client is responsible for providing the URL structure. However, it is highly unlikely that in your solution it is appropriate for the client to provide the URL structure. by Joshcodes, 11.09.2015 14:49
This was the most helpful resource by far showing the difference between PUT /users/John and POST /users/John. Thanks. by PRMan, 30.06.2018 18:40
Of course you can POST an 'update'. If you keep prior versions around (and there are many reasons why you may want to do so) then your update is not idempotent and so cannot be expressed by PUT. (Or in other words everything turns into a collection when you stare at it hard enough) by CurtainDog, 05.09.2018 06:20
upvoted! curious question when you do insert on conflict do nothing, i am guessing post is what should be used since put would actually replace it by PirateApp, 04.02.2020 04:02
Show remaining 10 comments
16
217

POST means "create new" as in "Here is the input for creating a user, create it for me".

PUT means "insert, replace if already exists" as in "Here is the data for user 5".

You POST to example.com/users since you don't know the URL of the user yet, you want the server to create it.

You PUT to example.com/users/id since you want to replace/create a specific user.

POSTing twice with the same data means create two identical users with different ids. PUTing twice with the same data creates the user the first and updates him to the same state the second time (no changes). Since you end up with the same state after a PUT no matter how many times you perform it, it is said to be "equally potent" every time - idempotent. This is useful for automatically retrying requests. No more 'are you sure you want to resend' when you push the back button on the browser.

A general advice is to use POST when you need the server to be in control of URL generation of your resources. Use PUT otherwise. Prefer PUT over POST.

23.10.2011 14:27
Comments
Sloppiness may have cause it to be commonly taught that there are only two verbs you need: GET and POST. GET to obtain, POST to change. Even PUT and DELETE were performed using POST. Asking what PUT really means 25 years later maybe a sign we learned it wrong at first. REST popularity drove people back to the basics where we must now unlearn past bad mistakes. POST was overused and now commonly taught incorrectly. Best part: "POSTing twice with the same data means create two identical [resources]". Great point! by maxpolk, 01.09.2014 19:36
How can you use PUT to create a record by the ID, like in your example user 5 if it doesn't exist yet? Don't you mean update, replace if already exists? or something by Luke, 28.11.2014 12:44
@Coulton: I meant what I wrote. You insert user 5 if you PUT to /users/5 and #5 does not exist yet. by Alexander Torstling, 28.11.2014 15:46
@Coulton: And PUT can also be used to replace the value of an existing resource in its entirety. by DavidRR, 16.12.2014 14:02
"Prefer PUT over POST"... care to justify that? by thecoshman, 08.06.2015 08:04
@thecoshman: Sure. I wrote that as a general advise. My reasoning is that PUT is idempotent, hence better from a network perspective. POST is also more general, so by recommending PUT you avoid POST being used for situations where PUT would have sufficed. POST is also heavily overused due to browser restrictions, and so a recommendation against it will have positive effects for REST as a concept. There are also some positive effects in the URL scheme when the clients are in control of the URL construction IMO, but I cannot fit that into a comment here. by Alexander Torstling, 08.06.2015 09:08
@AlexanderTorstling excuse whilst I try to tease out solid reasoning others might benefit from. Better from a network perspective how? Sure if your network goes down and you failed to confirmation you can just re-create, but what if it did work, and then someone else modified? Your re-PUT will overwrite what they did. You make it sound like POST has some extra overhead compared to PUT (where PUT would have sufficed). I think the fact POST is overused should not mean we advise against it when it is the correct choice, just learn to advise the right choices. That Last point is rather subjective. by thecoshman, 08.06.2015 13:09
@thecoshman: I was thinking of retries, yes. PUT concurrency can be controlled by conditional headers like If-Modified et al. Doing the same for POST would result in much coarser locking. You have a point in advocating the right choices, I however had no intention of banning POST. Perhaps "Use PUT when possible" would have been a better wording? by Alexander Torstling, 08.06.2015 14:28
@AlexanderTorstling well, my main point was that your answer states you should have a preference, with no justification for it. Your responses here however seem fairly justifiable. That said, I don't think it's the correct reasoning to use for PUT vs POST by thecoshman, 09.06.2015 16:12
Here is one benefit that using POST to create a resource has over PUT. In this case, if you try to modify a resource that doesn't exist yet (using PUT), you will get an error. To generalize this advice beyond PUT vs POST, try to not to use an interface where the result/action depends on the current state, because the user may have an incorrect assumption about what the current state is (in the put example, he thinks the resource already exists). Use two separate interfaces and throw an error if the current state does not match the preconditions. by Kevin Wheeler, 08.09.2015 23:07
PS I still don't understand what is meant by "Better from a network perspective." I can, however, think of at least one reason on my own as to why PUT would be better from a network perspective: the results can be cached (perhaps by a proxy cache server). by Kevin Wheeler, 08.09.2015 23:10
I would say that POSTing twice with the same data MAY result in two identical users. Were I creating my API, if someone tried to POST a new user with the same email address, but different data, I might issue a 409. If someone tried to POST a new user with identical data, I might issue a 303. I probably wouldn't want my system to be able to have two identical users. by Dan Jones, 27.12.2015 16:24
I don't think this is true at least for App with database ... so if I have a POST */createUser/diego and PUT */createUser/jose , and I clicked twice and both with the method persisted() , it will insert 4 records. by diego matos - keke, 16.03.2016 22:58
@diegomatos-keke: You are not supposed to PUT or POST to a verb URI like "createUser". You are supposed to POST to '*/users' to create Diego and PUT to '*/users/diego' to update Diego. If you click twice for the POST, you will create 2 Diegos. But if you click twice for the PUT, you will update Diego twice, but not create 2 Diegos. by Alexander Torstling, 17.03.2016 08:42
@AlexanderTorstling commenting to point your attention to stackoverflow.com/questions/39057416/…. maybe you can help. by Roam, 20.08.2016 19:23
it is ok according to RFC tools.ietf.org/html/rfc2616#page-54 by F.Tamy, 07.09.2020 07:17
Show remaining 11 comments
4
175

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

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

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

PUT /user/12345 HTTP/1.1  <--- update the user
Host: mydomain.com
15.01.2011 19:59
Comments
Actually, it should be POST /users. (Note that /users is plural.) This has the affect of creating a new user and making it a child resource of the /users collection. by DavidRR, 16.12.2014 13:54
@DavidRR to be fair, how to handle groups is another debate altogether. GET /users makes sense, it reads as you want, but I'd be ok with GET /user/<id> or POST /user (with payload for said new user) because it reads correctly 'get me users 5' is odd, but 'get me user 5' is more natural. I'd probably still fall down on the side of pluralisation though :) by thecoshman, 08.06.2015 07:57
@thecoshman You can read it like 'from users get me id 5' ;) by xuiqzy, 08.11.2020 11:56
@xuiqzy hmm, I quite like this way of thinking about it really, and expands nicely GET /users/5/documents/4/title would be like 'get the users, from there get me user 5, from there get me the documents, from there get me document 4, from there get me the title' by thecoshman, 17.11.2020 22:54
8
135

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
10.03.2009 14:28
Comments
POST /items adds a new item to an already defined resource ('item'). It does not, as the answer says, "create a group." I don't understand why this has 12 votes. by David J., 21.06.2012 05:26
Out of the box, Rails does not support 'creating a group' via REST. To 'create a group' by which I mean 'create a resource' you have to do it via the source code. by David J., 21.06.2012 05:28
It has 12 votes because it predates the change that was made that added the group thing. I've reverted the change. by Tim Sullivan, 21.06.2012 15:20
This is a fair guideline, but an oversimplification. As the other answers mention, either method could be used for both create and update. by Brad Koch, 07.03.2013 15:55
I agree with the answer with a slight modification. Use POST to create and PUT to update the resource completely. For partial updates, we can use PUT or PATCH. Lets say we want to update the status of a group. We can use PUT /groups/1/status with the status is the request payload or PATCH /groups/1 with the details about the action in the payload by java_geek, 06.10.2014 06:26
@BradKoch You are right with the statement; but when you are designing a RESTful API, you need to ensure that its consistent so that it makes life easy for clients consuming your API's. If you are using POST/PUT interchangeably to create/update resources it makes life hard for your consumer. You would want to keep it easy for your clients because thats how you grow your consumer base. by java_geek, 06.10.2014 06:38
It should also be made clear that PUT /items/42 is also valid for creating a resource, but only if the client has the privilege of naming the resource. (Does Rails allow a client this naming privilege?) by DavidRR, 16.12.2014 14:10
Nice and short +1. For extra details one can read further :) by Akif, 23.02.2021 13:06
Show remaining 3 comments
3
135

Both are used for data transmission between client to server, but there are subtle differences between them, which are:

Enter image description here

Analogy:

  • PUT i.e. take and put where it was.
  • POST as send mail in post office.

enter image description here

Social Media/Network Analogy:

  • Post on social media: when we post message, it creates new post.
  • Put(i.e. edit) for the message we already Posted.
11.09.2015 13:12
Comments
@MobileMon No, REST methods are not CRUD. by jlr, 08.01.2016 19:06
I'd say PUT for UPSERTS by Hola Soy Edu Feliz Navidad, 26.11.2018 11:45
@MobileMon no : POST when you create a new resource and you don't know the final endpoint to get it. PUT for other cases. by Portekoi, 19.07.2019 13:33
9
69

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.

10.03.2009 15:27
Comments
There's nothing wrong with allowing PUT to create resources. Just be aware that it means that the client provides the URL. by Julian Reschke, 07.04.2010 07:47
There's something very wrong with allowing PUT to create resources: the client provides the URL. That's the server's job! by Joshcodes, 29.10.2013 17:33
@Joshcodes It is not always the case that it is the server's job to create client ids. I have increasingly seen designs that let clients generate some sort of UUID as the resource id. This design lends itself in particular to increase scale. by Justin Ohms, 05.02.2017 18:26
@JustinOhms I agree with your point about client generated IDs (side note: all systems designed by me since circa 2008 require the client to create the ID as a UUID/Guid). That does not mean the client should specify the URL. by Joshcodes, 06.02.2017 18:24
@Joshcodes It's matter of separating concerns. Where the URL is generated is actually of little consequence. Yes the server is responsible for delivering content from the correct URL but that does not limit a server from responding to a request on an incorrect URL. The correct response from the server in this case is a 308. A proper client will then retry the PUT on the correct URL. Another example is a distributed system where not all nodes know of all resource provided by clients. Here a PUT to create would be perfectly valid because for that server node the resource does not exist. by Justin Ohms, 06.02.2017 19:48
@JustinOhms I agree completely it's about separating concerns. I also agree there are edge cases for using PUT (one encountered recently by me involved a data import than needed the ability to re-run). The approach you have outlined above works because the server "instruct(s) clients on how to construct appropriate URIs", (Roy Fielding's words). However, it is not obvious to me why that is better than just using POST as intended. by Joshcodes, 06.02.2017 20:48
@Joshcodes The reason to use a PUT like this in a multi node setup is that that for the client to switch from PUT to POST the client would require knowledge about the state of the data on that node. It seems odd because we are often think of the server as being a single authority however in a distributed system with eventual consistency the client may actually have more information than any given server node at any point in time. In this case the client knows the resource exists, the node does not. (maybe a sync is needed) Plus POST would not be appropriate because the resource does exist. by Justin Ohms, 06.02.2017 21:28
Yes, if the resource already exists, use PUT. However, in nearly all cases, the resources should be created with POST and the client should not provide the URL. Roy Fielding agrees with this statement FWIW: roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driv‌​en by Joshcodes, 07.02.2017 01:26
Any reference for "with some input from Roy Fielding"? by wlnirvana, 27.04.2020 07:28
Show remaining 4 comments
11
63

The decision of whether to use PUT or POST to create a resource on a server with an HTTP + REST API is based on who owns the URL structure. Having the client know, or participate in defining, the URL struct is an unnecessary coupling akin to the undesirable couplings that arose from SOA. Escaping types of couplings is the reason REST is so popular. Therefore, the proper method to use is POST. There are exceptions to this rule and they occur when the client wishes to retain control over the location structure of the resources it deploys. This is rare and likely means something else is wrong.

At this point some people will argue that if RESTful-URL's are used, the client does knows the URL of the resource and therefore a PUT is acceptable. After all, this is why canonical, normalized, Ruby on Rails, Django URLs are important, look at the Twitter API … blah blah blah. Those people need to understand there is no such thing as a Restful-URL and that Roy Fielding himself states that:

A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. [Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC's functional coupling].

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

The idea of a RESTful-URL is actually a violation of REST as the server is in charge of the URL structure and should be free to decide how to use it to avoid coupling. If this confuses you read about the significance of self discovery on API design.

Using POST to create resources comes with a design consideration because POST is not idempotent. This means that repeating a POST several times does not guarantee the same behavior each time. This scares people into using PUT to create resources when they should not. They know it's wrong (POST is for CREATE) but they do it anyway because they don't know how to solve this problem. This concern is demonstrated in the following situation:

  1. The client POST a new resource to the server.
  2. The server processes the request and sends a response.
  3. The client never receives the response.
  4. The server is unaware the client has not received the response.
  5. The client does not have a URL for the resource (therefore PUT is not an option) and repeats the POST.
  6. POST is not idempotent and the server …

Step 6 is where people commonly get confused about what to do. However, there is no reason to create a kludge to solve this issue. Instead, HTTP can be used as specified in RFC 2616 and the server replies:

10.4.10 409 Conflict

The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request. The response body SHOULD include enough

information for the user to recognize the source of the conflict. Ideally, the response entity would include enough information for the user or user agent to fix the problem; however, that might not be possible and is not required.

Conflicts are most likely to occur in response to a PUT request. For example, if versioning were being used and the entity being PUT included changes to a resource which conflict with those made by an earlier (third-party) request, the server might use the 409 response to indicate that it can’t complete the request. In this case, the response entity would likely contain a list of the differences between the two versions in a format defined by the response Content-Type.

Replying with a status code of 409 Conflict is the correct recourse because:

  • Performing a POST of data which has an ID which matches a resource already in the system is “a conflict with the current state of the resource.”
  • Since the important part is for the client to understand the server has the resource and to take appropriate action. This is a “situation(s) where it is expected that the user might be able to resolve the conflict and resubmit the request.”
  • A response which contains the URL of the resource with the conflicting ID and the appropriate preconditions for the resource would provide “enough information for the user or user agent to fix the problem” which is the ideal case per RFC 2616.

Update based on release of RFC 7231 to Replace 2616

RFC 7231 is designed to replace 2616 and in Section 4.3.3 describes the follow possible response for a POST

If the result of processing a POST would be equivalent to a representation of an existing resource, an origin server MAY redirect the user agent to that resource by sending a 303 (See Other) response with the existing resource's identifier in the Location field. This has the benefits of providing the user agent a resource identifier and transferring the representation via a method more amenable to shared caching, though at the cost of an extra request if the user agent does not already have the representation cached.

It now may be tempting to simply return a 303 in the event that a POST is repeated. However, the opposite is true. Returning a 303 would only make sense if multiple create requests (creating different resources) return the same content. An example would be a "thank you for submitting your request message" that the client need not re-download each time. RFC 7231 still maintains in section 4.2.2 that POST is not to be idempotent and continues to maintain that POST should be used for create.

For more information about this, read this article.

29.10.2013 23:00
Comments
Would a 409 Conflict response be the appropriate code for something like trying to create a new account with a username that already exists? I've been using 409 for versioning conflicts specifically, but after reading your answer, I wonder if it shouldn't be used for any "duplicate" requests. by Eric B., 09.07.2014 04:43
@EricB. Yes, in the situation you describe "due to a conflict with the current state of the resource" the operation fails. Additionally, it is reasonable to expect that the user can resolve the conflict and the message body only needs to inform the user that the username already exists. by Joshcodes, 10.07.2014 13:25
@Joshcodes can you say more about the conflict resolution process? In this case, if the username already exists is the client expected to prompt the end user for a different username? What if the client is actually trying to use POST to change the username? Should PUT requests still be used for updating parameters, while POST is used for creating objects whether it be one at a time or several? Thanks. by BFar, 22.01.2015 22:41
@BFar2 if the username already exists then the client should prompt the user. To change the username, assuming the username is part of an already created resource which needs modified, PUT would be used because you are correct, POST is used for create, always and PUT for updates. by Joshcodes, 23.01.2015 01:09
explaining things using short and effective language is also a desirable skill by Junchen Liu, 24.08.2015 16:27
@Joshcodes i'm seeking an answer to stackoverflow.com/questions/39057416/…. commenting now to point your attention to it. by Roam, 20.08.2016 19:20
@Joshcodes i'm aware the work on stackoverflow.com/questions/39057416/… doesn't comply w/Restful architecture. yet works for our case as an exception. by Roam, 20.08.2016 19:21
@Joshcodes Interesting. to clarify: Performing a POST of data which has an ID which matches a resource already in the system is a conflict" Isn't your prescription that a POST never includes an ID since the server decides the ID? by Iain, 23.09.2017 23:46
Iain, the client determines the ID. The server determines the URL. by Joshcodes, 24.09.2017 14:01
@Joshcodes How is the client to determine the ID? Generating a UUID? What about apps that just use the auto-incrementing table ID; something I see a lot. Is this just bad practice? by Kenmore, 25.02.2018 01:41
@Zuko, In my opinion, auto-incrementing table IDs have no place in a distributed environment. UUID's are superior in every way except storage space. Ints for IDs are a holdover from when DB storage was a larger concern that it is today. by Joshcodes, 05.03.2018 18:14
Show remaining 6 comments
1
53

I like this advice, from RFC 2616's definition of PUT:

The fundamental difference between the POST and PUT requests is reflected in the different meaning of the Request-URI. The URI in a POST request identifies the resource that will handle the enclosed entity. That resource might be a data-accepting process, a gateway to some other protocol, or a separate entity that accepts annotations. In contrast, the URI in a PUT request identifies the entity enclosed with the request -- the user agent knows what URI is intended and the server MUST NOT attempt to apply the request to some other resource.

This jibes with the other advice here, that PUT is best applied to resources that already have a name, and POST is good for creating a new object under an existing resource (and letting the server name it).

I interpret this, and the idempotency requirements on PUT, to mean that:

  • POST is good for creating new objects under a collection (and create does not need to be idempotent)
  • PUT is good for updating existing objects (and update needs to be idempotent)
  • POST can also be used for non-idempotent updates to existing objects (especially, changing part of an object without specifying the whole thing -- if you think about it, creating a new member of a collection is actually a special case of this kind of update, from the collection's perspective)
  • PUT can also be used for create if and only if you allow the client to name the resource. But since REST clients aren't supposed to make assumptions about URL structure, this is less in the intended spirit of things.
11.01.2012 17:18
Comments
"POST can also be used for non-idempotent updates to existing objects (especially, changing part of an object without specifying the whole thing" That's what PATCH is for by Snuggs, 04.05.2012 22:11
3
49

In short:

PUT is idempotent, where the resource state will be the same if the same operation is executed one time or multiple times.

POST is non-idempotent, where the resource state may become different if the operation is executed multiple times as compared to executing a single time.

Analogy with database query

PUT You can think of similar to "UPDATE STUDENT SET address = "abc" where id="123";

POST You can think of something like "INSERT INTO STUDENT(name, address) VALUES ("abc", "xyzzz");

Student Id is auto generated.

With PUT, if the same query is executed multiple times or one time, the STUDENT table state remains the same.

In case of POST, if the same query is executed multiple times then multiple Student records get created in the database and the database state changes on each execution of an "INSERT" query.

NOTE: PUT needs a resource location (already-resource) on which update needs to happen, whereas POST doesn't require that. Therefore intuitively POST is meant for creation of a new resource, whereas PUT is needed for updating the already existing resource.

Some may come up with that updates can be performed with POST. There is no hard rule which one to use for updates or which one to use for create. Again these are conventions, and intuitively I'm inclined with the above mentioned reasoning and follow it.

29.07.2016 11:11
Comments
for PUT is similar to INSERT or UPDATE query by Eugen Konkov, 22.08.2016 09:25
actually PUT You can think of similar to "UPDATE STUDENT SET address = "abc" where id="123"; would be a statement for PATCH. "UPDATE STUDENT SET address = "abc", name="newname" where id="123" would be a correct analogy for PUT by mko, 12.04.2017 13:24
Put could also be used for INSERT. For example if you server detected you were trying to upload the same file multiple times, it would make your request idempotent. (No new file uploads are done). by kiwicomb123, 20.08.2018 22:46
10
43

POST is like posting a letter to a mailbox or posting an email to an email queue. PUT is like when you put an object in a cubby hole or a place on a shelf (it has a known address).

With POST, you're posting to the address of the QUEUE or COLLECTION. With PUT, you're putting to the address of the ITEM.

PUT is idempotent. You can send the request 100 times and it will not matter. POST is not idempotent. If you send the request 100 times, you'll get 100 emails or 100 letters in your postal box.

A general rule: if you know the id or name of the item, use PUT. If you want the id or name of the item to be assigned by the receiving party, use POST.

POST versus PUT

14.06.2013 18:10
Comments
No, PUT implies that you know the URL. If you only know the ID then POST with that ID to get the URL. by Joshcodes, 29.10.2013 17:35
The id is part of the URL, so yes, use PUT if you know the URL (which includes the id). by Homer6, 29.10.2013 22:02
No, the URL is determined by the server and the ID is not necessarily part of the URL. Roy Fielding would tell you the same or you could just read his thesis. by Joshcodes, 29.10.2013 23:06
@Joshcodes, is that assuming REST? In a RESTful architecture, the item id is most definitely part of the URL, as in: /people/123. I like this site for REST: microformats.org/wiki/rest/urls by Beez, 26.12.2013 19:10
@Beez the mircoformats link suggests a good way for servers to structure their URLs but the server determines the URL. The client next-to-never does. See my answer or associated article if you don't understand this. by Joshcodes, 07.01.2014 17:11
@Joshcodes, I'm not denying where a URL is determined. I'm saying that in a RESTful architecture (defined from the server on up), the ID is part of a URL. by Beez, 07.01.2014 20:21
@Beez if the server determines the URL, the URL should not be dictated by the client. Therefore, even if you know the ID, use POST not PUT. Whether the ID should be part of the URL is a different conversation. by Joshcodes, 07.01.2014 21:16
I think "General Rule" covers it generally having the ID or name in the URL. Great answer! by TamusJRoyce, 11.05.2015 04:48
@TamusJRoyce, Roy Fielding (the guy who created REST) would disagree with you: roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driv‌​en Also, while true that the ID will likely be provide by the client via the URL the client still does not know where in the URL to put the ID. by Joshcodes, 11.09.2015 14:44
@beez and Homer6: Joshcodes is correct. Nothing about REST requires the ID to be in the URL, and a URL with a structure like /collection/:id does not imply that the website is RESTful. In fact, sites with non-HTML representations almost always aren't. by Nicholas Shanks, 26.12.2016 13:22
Show remaining 5 comments
1
39

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.

15.10.2017 02:33
Comments
Your short answer might be VERY wrong. HTTP PUT is free to be repeated by HTTP proxies. And so, if PUT is actually doing SQL INSERT it might fail second time, which means it would return different result and so it would not be IDEMPOTENT (which is the difference between PUT and POST) by Kamil Tomšík, 30.04.2018 17:27
4
40

New answer (now that I understand REST better):

PUT is merely a statement of what content the service should, from now on, use to render representations of the resource identified by the client; POST is a statement of what content the service should, from now on, contain (possibly duplicated) but it's up to the server how to identify that content.

PUT x (if x identifies a resource): "Replace the content of the resource identified by x with my content."

PUT x (if x does not identify a resource): "Create a new resource containing my content and use x to identify it."

POST x: "Store my content and give me an identifier that I can use to identify a resource (old or new) containing said content (possibly mixed with other content). Said resource should be identical or subordinate to that which x identifies." "y's resource is subordinate to x's resource" is typically but not necessarily implemented by making y a subpath of x (e.g. x = /foo and y = /foo/bar) and modifying the representation(s) of x's resource to reflect the existence of a new resource, e.g. with a hyperlink to y's resource and some metadata. Only the latter is really essential to good design, as URLs are opaque in REST -- you're supposed to use hypermedia instead of client-side URL construction to traverse the service anyways.

In REST, there's no such thing as a resource containing "content". I refer as "content" to data that the service uses to render representations consistently. It typically consists of some related rows in a database or a file (e.g. an image file). It's up to the service to convert the user's content into something the service can use, e.g. converting a JSON payload into SQL statements.

Original answer (might be easier to read):

PUT /something (if /something already exists): "Take whatever you have at /something and replace it with what I give you."

PUT /something (if /something does not already exist): "Take what I give you and put it at /something."

POST /something: "Take what I give you and put it anywhere you want under /something as long as you give me its URL when you're done."

01.08.2012 20:10
Comments
But how can you use PUT to create a new resource if it doesn't exist, while your ID generation method is on Auto Increment ? Usually ORM's does auto generate the ID for you, like the way you want it to be in a POST for example. Does it mean that if you want to implement PUT the right way you have to change your id auto generation ? This is awkward if the answer is yes. by Roni Axelrad, 16.09.2018 15:28
@RoniAxelrad : PUT is like a database "INSERT OR UPDATE" statement where you are including the key in the statement, so only applicable where you can guarente no collisions. eg. your domain has a 'natural key' or you use a guid. POST is like inserting into a table with an auto incrementing key. You have to be told by the database what ID it got after it has been inserted. Note your "INSERT OR UPDATE" will replace any previous data if it existed. by Nigel Thorne, 26.11.2018 01:33
@NigelThorne Thanks for your answer. So if for example I'm trying to PUT a book id 10 with a URI: PUT books/10. If book id 10 does not exists, I should create a book with id 10 right? but I cannot control the creation ID numerator, because it's auto increment. what should I do in that situation ? by Roni Axelrad, 27.11.2018 20:50
@RoniAxelrad REST PUT to an ID that doesn't exist is a request to the server to create a resource. It's still up to the server to decide if it wants to allow that. The server is in charge. It can respond with "No. I'm not going to do that". You already do that if the user doesn't have enough permissions...etc. It's okay for the server to say "No". REST is a convention that lets us define the meaning of various types of request ... your server decides what to do with those requests based on your business logic :) Even if it says "no" it's still following REST :) by Nigel Thorne, 03.12.2018 07:03
0
37

Ruby on Rails 4.0 will use the 'PATCH' method instead of PUT to do partial updates.

RFC 5789 says about PATCH (since 1995):

A new method is necessary to improve interoperability and prevent errors. The PUT method is already defined to overwrite a resource with a complete new body, and cannot be reused to do partial changes. Otherwise, proxies and caches, and even clients and servers, may get confused as to the result of the operation. POST is already used but without broad interoperability (for one, there is no standard way to discover patch format support). PATCH was mentioned in earlier HTTP specifications, but not completely defined.

"Edge Rails: PATCH is the new primary HTTP method for updates" explains it.

26.02.2012 09:21
10
28

At the risk of restating what has already been said, it seems important to remember that PUT implies that the client controls what the URL is going to end up being, when creating a resource. So part of the choice between PUT and POST is going to be about how much you can trust the client to provide correct, normalized URL that are coherent with whatever your URL scheme is.

When you can't fully trust the client to do the right thing, it would be more appropriate to use POST to create a new item and then send the URL back to the client in the response.

25.03.2011 10:17
Comments
I'm a bit late to this - but someone saying something similar on another website got it to click for me. If you're creating a resource and using an auto-incremented ID as it's "identifier" instead of a user assigned name, it should be a POST. by Ixmatus, 03.02.2012 18:51
This isn't quite right - PUT can still create a resource by referring to it with a non-canonical name, as long as in the response, the server returns a Location header that does contain the canonical resource name. by Ether, 19.10.2012 16:08
@Joshcodes don't forget that you can have many URIs referencing the same underlying resource. So what Ether said is sound advice, the client can PUT to a URL (that might be more semantic, like PUT /X-files/series/4/episodes/max) and the server respond with a URI that provides a short canonical unique link to that new resource (ie /X-Ffiles/episodes/91) by thecoshman, 08.06.2015 08:02
@thecoshman the issue is the concern for the URL structure does not belong to the client. Reading about self-discovery (also part of REST) may help make this clear. by Joshcodes, 08.06.2015 17:50
@Joshcodes then by that logic, a client should never use PUT to create as they shouldn't be concerned with with providing the URL. Well... unless the server provided a URL to PUT to if the client wants to put to it... something like "PUT /comments/new" and the server might respond "204 /comments/234532" but that seems a bit RPC to me, the client should just POST to /comments... by thecoshman, 09.06.2015 16:18
@thecoshman yes, the client really should never use PUT. What's RPC about that? by Joshcodes, 10.06.2015 17:11
@thecoshman: no, you can't have multiple URLs pointing to one resource. Every unique URI is a unique resource, and every resource has one and only one URI. by Nicholas Shanks, 26.12.2016 13:38
@NicholasShanks not really. Consider a resource that represents a school student, you could access /student/123 but you might also get to that same student via /class/abc/student/123, That is perfectly valid. There is the concept of the canonical URI though, which in this case we could say the former is. The U is for Uniform, not Unique. by thecoshman, 09.01.2017 13:41
@thecoshman What you would then have is two identical resources that just happen to change every time the other one does. A link from one to the other with a canonical relation would definitely help though. Even if you supplied a Content-Location header with one, pointing to the path of the other, that would not unify the underlying resources represented by each URL. Consider that a representation is not a resource, and two identical representations do not make the same resource (e.g. downloads/v1.0.0/ and downloads/latest-version/) by Nicholas Shanks, 09.01.2017 15:34
@NicholasShanks I think this answer provides a good explanation that I agree with but also considers your point of view. I'd also say that it is probably a more relevant place for this discussion. by thecoshman, 09.01.2017 16:48
Show remaining 5 comments
2
26

In a very simple way I'm taking the example of the Facebook timeline.

Case 1: When you post something on your timeline, it's a fresh new entry. So in this case they use the POST method because the POST method is non-idempotent.

Case 2: If your friend comment on your post the first time, that also will create a new entry in the database so the POST method used.

Case 3: If your friend edits his comment, in this case, they had a comment id, so they will update an existing comment instead of creating a new entry in the database. Therefore for this type of operation use the PUT method because it is idempotent.*

In a single line, use POST to add a new entry in the database and PUT to update something in the database.

14.02.2017 06:55
Comments
If the comment is an object with property like user id, created date, comment-message, etc. and at the time of edit only comment-message is getting updated, PATCH should be done here? by Mohammed H, 12.08.2017 10:47
PUT is used by FB to update the comment because an existing resource is being updated, and that is what PUT does (updates a resource). PUT happens to be idempotent, in contrast to POST. An HTTP verb being idempotent affects the error handling but does not dictate usage. See my answer for a more detail explanation: stackoverflow.com/questions/630453/put-vs-post-in-rest/… by Joshcodes, 19.06.2018 12:57
6
24

The most important consideration is reliability. If a POST message gets lost the state of the system is undefined. Automatic recovery is impossible. For PUT messages, the state is undefined only until the first successful retry.

For instance, it may not be a good idea to create credit card transactions with POST.

If you happen to have auto generated URI's on your resource you can still use PUT by passing a generated URI (pointing to an empty resource) to the client.

Some other considerations:

  • POST invalidates cached copies of the entire containing resource (better consistency)
  • PUT responses are not cacheable while POST ones are (Require Content-Location and expiration)
  • PUT is less supported by e.g. Java ME, older browsers, firewalls
08.02.2012 16:31
Comments
This is incorrect. For POST, the state is also undefined only until the first successful retry. Then, either the server accepts the POST (message never arrived), throws a 409 conflict for a duplicate ID (message arrived, response was lost), or any other valid response. by Joshcodes, 24.04.2014 12:13
In general a useragent would not able to safely retry the POST operation since the POST operation gives no that guarantee that two operations would have the same effect as one. The term "ID" has nothing to do with HTTP. The URI identifies the resource. by Hans Malherbe, 25.07.2014 05:48
A useragent can "safely" retry a POST operation as many times as it wants. It will just receive a duplicate ID error (assuming the resource has an ID) or a duplicate data error (assuming that's an issue and the resource does not have IDs). by Joshcodes, 27.07.2014 02:10
Bangs head against wall. HTTP has no solution to the problem of reliability, and this is not well understood, not much discussed, and simply not catered for in the vast majority of web applications. @Joshcodes I have an answer to this question. I essentially agree with Hans. There's a problem. by bbsimonbb, 13.06.2018 08:21
@bbsimonbb, HTTP has a robust and well documented set of error responses. My answer to this question (stackoverflow.com/questions/630453/put-vs-post-in-rest/…) covers how to use http according to specification to achieve consistency. by Joshcodes, 19.06.2018 12:50
invalidates cached copies of the entire containing resource any reference for that? Also it's never mandatory for a browser to follow the cache rules set. by Honey, 26.11.2018 16:50
Show remaining 1 comments
2
22

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

25.09.2018 08:28
Comments
Why was this not upvoted? If true, this is a critical distinction is it not? by Iofacture, 29.09.2018 03:02
I faced it when implementing API for the profile update, which includes user profile pic upload. Then I tested it with the postman, Ajax, PHP curl and laravel 5.6 as backend. by Rohit Dhiman, 29.09.2018 06:54
1
17

Readers new to this topic will be struck by the endless discussion about what you should do, and the relative absence of lessons from experience. The fact that REST is "preferred" over SOAP is, I suppose, a high-level learning from experience, but goodness we must have progressed from there? It's 2016. Roy's dissertation was in 2000. What have we developed? Was it fun? Was it easy to integrate with? To support? Will it handle the rise of smartphones and flaky mobile connections?

According to ME, real-life networks are unreliable. Requests timeout. Connections are reset. Networks go down for hours or days at a time. Trains go into tunnels with mobile users aboard. For any given request (as occasionally acknowledged in all this discussion) the request can fall in the water on its way, or the response can fall in the water on its way back. In these conditions, issuing PUT, POST and DELETE requests directly against substantive resources has always struck me as a little brutal and naive.

HTTP does nothing to ensure reliable completion of the request-response, and that's just fine because this is properly the job of network-aware applications. Developing such an application, you can jump through hoops to use PUT instead of POST, then more hoops to give a certain kind of error on the server if you detect duplicate requests. Back at the client, you then have to jump through hoops to interpret these errors, refetch, revalidate and repost.

Or you can do this: consider your unsafe requests as ephemeral single-user resources (let's call them actions). Clients request a new "action" on a substantive resource with an empty POST to the resource. POST will be used only for this. Once safely in possession of the URI of the freshly minted action, the client PUTs the unsafe request to the action URI, not the target resource. Resolving the action and updating the "real" resource is properly the job of your API, and is here decoupled from the unreliable network.

The server does the business, returns the response and stores it against the agreed action URI. If anything goes wrong, the client repeats the request (natural behaviour!), and if the server has already seen it, it repeats the stored response and does nothing else.

You will quickly spot the similarity with promises: we create and return the placeholder for the result before doing anything. Also like a promise, an action can succeed or fail one time, but its result can be fetched repeatedly.

Best of all, we give sending and receiving applications a chance to link the uniquely identified action to uniqueness in their respective environments. And we can start to demand, and enforce!, responsible behaviour from clients: repeat your requests as much as you like, but don't go generating a new action until you're in possession of a definitive result from the existing one.

As such, numerous thorny problems go away. Repeated insert requests won't create duplicates, and we don't create the real resource until we're in possession of the data. (database columns can stay not-nullable). Repeated update requests won't hit incompatible states and won't overwrite subsequent changes. Clients can (re)fetch and seamlessy process the original confirmation for whatever reason (client crashed, response went missing, etc.).

Successive delete requests can see and process the original confirmation, without hitting a 404 error. If things take longer than expected, we can respond provisionally, and we have a place where the client can check back for the definitive result. The nicest part of this pattern is its Kung-Fu (Panda) property. We take a weakness, the propensity for clients to repeat a request any time they don't understand the response, and turn it into a strength :-)

Before telling me this is not RESTful, please consider the numerous ways in which REST principles are respected. Clients don't construct URLs. The API stays discoverable, albeit with a little change in semantics. HTTP verbs are used appropriately. If you think this is a huge change to implement, I can tell you from experience that it's not.

If you think you'll have huge amounts of data to store, let's talk volumes: a typical update confirmation is a fraction of a kilobyte. HTTP currently gives you a minute or two to respond definitively. Even if you only store actions for a week, clients have ample chance to catch up. If you have very high volumes, you may want a dedicated acid-compliant key value store, or an in-memory solution.

18.02.2016 11:45
Comments
Wont storing response be like maintaining a session? Which would cause (horizontal) scaling issues. by Saurabh Harwande, 21.08.2018 17:57
2
15

There seems to always be some confusion as to when to use the HTTP POST versus the HTTP PUT method for REST services. Most developers will try to associate CRUD operations directly to HTTP methods. I will argue that this is not correct and one can not simply associate the CRUD concepts to the HTTP methods. That is:

Create => HTTP PUT
Retrieve => HTTP GET
Update => HTTP POST
Delete => HTTP DELETE

It is true that the R(etrieve) and D(elete) of the CRUD operations can be mapped directly to the HTTP methods GET and DELETE respectively. However, the confusion lies in the C(reate) and U(update) operations. In some cases, one can use the PUT for a create while in other cases a POST will be required. The ambiguity lies in the definition of an HTTP PUT method versus an HTTP POST method.

According to the HTTP 1.1 specifications the GET, HEAD, DELETE, and PUT methods must be idempotent, and the POST method is not idempotent. That is to say that an operation is idempotent if it can be performed on a resource once or many times and always return the same state of that resource. Whereas a non idempotent operation can return a modified state of the resource from one request to another. Hence, in a non idempotent operation, there is no guarantee that one will receive the same state of a resource.

Based on the above idempotent definition, my take on using the HTTP PUT method versus using the HTTP POST method for REST services is: Use the HTTP PUT method when:

The client includes all aspect of the resource including the unique identifier to uniquely identify the resource. Example: creating a new employee.
The client provides all the information for a resource to be able to modify that resource.This implies that the server side does not update any aspect of the resource (such as an update date).

In both cases, these operations can be performed multiple times with the same results. That is the resource will not be changed by requesting the operation more than once. Hence, a true idempotent operation. Use the HTTP POST method when:

The server will provide some information concerning the newly created resource. For example, take a logging system. A new entry in the log will most likely have a numbering scheme which is determined on the server side. Upon creating a new log entry, the new sequence number will be determined by the server and not by the client.
On a modification of a resource, the server will provide such information as a resource state or an update date. Again in this case not all information was provided by the client and the resource will be changing from one modification request to the next. Hence a non idempotent operation.

Conclusion

Do not directly correlate and map CRUD operations to HTTP methods for REST services. The use of an HTTP PUT method versus an HTTP POST method should be based on the idempotent aspect of that operation. That is, if the operation is idempotent, then use the HTTP PUT method. If the operation is non idempotent, then use the HTTP POST method.

10.10.2013 04:18
Comments
Update => HTTP POST : POST is not for updating by Premraj, 30.01.2016 00:57
@premraj You made the assumption that Burhan is telling you not to make; namely, you are conflating CRUD, REST, and HTTP. If you read RFC 7231, where these things are defined, you will find that in HTTP protocol, the definition of POST certainly allows updating. It is only the constraints of REST that say otherwise. by IAM_AL_X, 16.04.2020 03:32
1
13

the origin server can create the resource with that URI

So you use POST and probably, but not necessary PUT for resource creation. You don't have to support both. For me POST is perfectly enough. So it is a design decision.

As your quote mentioned, you use PUT for creation of there is no resource assigned to an IRI, and you want to create a resource anyway. For example, PUT /users/123/password usually replaces the old password with a new one, but you can use it to create a password if it does not exist already (for example, by freshly registered users or by restoring banned users).

16.01.2014 07:58
Comments
I think you've managed to provide one of the few good examples of how to use PUT, well done. by thecoshman, 08.06.2015 08:13
0
12

I'm going to land with the following:

PUT refers to a resource, identified by the URI. In this case, you are updating it. It is the part of the three verbs referring to resources -- delete and get being the other two.

POST is basically a free form message, with its meaning being defined 'out of band'. If the message can be interpreted as adding a resource to a directory, that would be OK, but basically you need to understand the message you are sending (posting) to know what will happen with the resource.


Because PUT and GET and DELETE refer to a resource, they are also by definition idempotent.

POST can perform the other three functions, but then the semantics of the request will be lost on the intermediaries such as caches and proxies. This also applies to providing security on the resource, since a post's URI doesn't necessarily indicate the resource it is applying to (it can though).

A PUT doesn't need to be a create; the service could error if the resource isn't already created, but otherwise update it. Or vice versa -- it may create the resource, but not allow updates. The only thing required about PUT is that it points to a specific resource, and its payload is the representation of that resource. A successful PUT means (barring interference) that a GET would retrieve the same resource.


Edit: One more thing -- a PUT can create, but if it does then the ID has to be a natural ID -- AKA an email address. That way when you PUT twice, the second put is an update of the first. This makes it idempotent.

If the ID is generated (a new employee ID, for example), then the second PUT with the same URL would create a new record, which violates the idempotent rule. In this case the verb would be POST, and the message (not resource) would be to create a resource using the values defined in this message.

21.10.2013 21:16
1
9

The semantics are supposed be different, in that "PUT", like "GET" is supposed to be idempotent -- meaning, you can the same exact PUT request multiple times and the result will be as if you executed it only once.

I will describe the conventions which I think are most widely used and are most useful:

When you PUT a resource at a particular URL what happens is that it should get saved at that URL, or something along those lines.

When you POST to a resource at a particular URL, often you are posting a related piece of information to that URL. This implies that the resource at the URL already exists.

For example, when you want to create a new stream, you can PUT it to some URL. But when you want to POST a message to an existing stream, you POST to its URL.

As for modifying the properties of the stream, you can do that with either PUT or POST. Basically, only use "PUT" when the operation is idempotent - otherwise use POST.

Note, however, that not all modern browsers support HTTP verbs other than GET or POST.

23.10.2011 20:07
Comments
What you describe POST as is actually how PATCH should behave. POST is supposed to mean something more akin to "append" as in "post to mailing list". by Alexander Torstling, 28.11.2014 15:57
0
9

Most of the time, you will use them like this:

  • POST a resource into a collection
  • PUT a resource identified by collection/:id

For example:

  • POST /items
  • PUT /items/1234

In both cases, the request body contains the data for the resource to be created or updated. It should be obvious from the route names that POST is not idempotent (if you call it 3 times it will create 3 objects), but PUT is idempotent (if you call it 3 times the result is the same). PUT is often used for "upsert" operation (create or update), but you can always return a 404 error if you only want to use it to modify.

Note that POST "creates" a new element in the collection, and PUT "replaces" an element at a given URL, but it is a very common practice to use PUT for partial modifications, that is, use it only to update existing resources and only modify the included fields in the body (ignoring the other fields). This is technically incorrect, if you want to be REST-purist, PUT should replace the whole resource and you should use PATCH for the partial update. I personally don't care much as far as the behavior is clear and consistent across all your API endpoints.

Remember, REST is a set of conventions and guidelines to keep your API simple. If you end up with a complicated work-around just to check the "RESTfull" box then you are defeating the purpose ;)

21.06.2017 17:38
0
7

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.

21.07.2014 20:02
5
8

Here's a simple rule:

PUT to a URL should be used to update or create the resource that can be located at that URL.

POST to a URL should be used to update or create a resource which is located at some other ("subordinate") URL, or is not locatable via HTTP.

11.12.2013 22:15
Comments
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. by thecoshman, 08.06.2015 08:10
Does the http spec say that? Or are you basing your comment on something else? by Adam Griffiths, 10.07.2016 20:41
It's just common sense, how you update something when you don't know what it is you are updating? POST is for creating a new resource. by thecoshman, 27.07.2016 09:23
thecoshman -- you are abusing semantics here -- a replace can be an update if it is the same resource with a few differences. A replace is only valid for put if replace is used to change the same resource. Replacing with a new and different resource is invalid (remove old and add new?), especially if the 'new' resource doesn't have a natural ID. POST, OTOH, is something that can create, update, replace, and delete -- using post depends on whether or not there is a message to interpret, such as 'apply the discount', which may or may not change the resource depending on logic. by Gerard ONeill, 28.12.2016 16:54
As for your second comment -- how about you 'get' the resource, modify the fields you need to, and then put it back? Or how about if the resource comes from a different source but uses a natural ID (the external ID) -- put would naturally update the resource at the URL when the original data changed. by Gerard ONeill, 28.12.2016 16:56
1
4

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

12.12.2013 11:06
Comments
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. by thecoshman, 08.06.2015 08:11
0
6

If you are familiar with database operations, there are

  1. Select
  2. Insert
  3. Update
  4. Delete
  5. Merge (Update if already existing, else insert)

I use PUT for Merge and update like operations and use POST for Insertions.

29.06.2016 21:13
1
5

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.

06.10.2014 06:51
Comments
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. by thecoshman, 08.06.2015 08:15
0
2

The request methods GET, PUT and DELETE are low-level data management operations (cf. RFC 7231, § 4.3.1, § 4.3.4 and § 4.3.5), i.e. CRUD operations (create, read, update and delete), on the target resource’s state (the one identified by the request URI):

  • GET should read a representation of the target resource’s state;
  • PUT should create or update the target resource’s state with the request’s representation;
  • DELETE should delete the state of the target resource.

In contrast, the request method POST is a high-level processing operation (cf. RFC 7231, § 4.3.3), i.e. a non-CRUD operation. POST should process the request’s representation. The processing may create a resource’s state but for a resource other than the target resource, otherwise it is a CRUD operation and PUT should be used for this.

So the fundamental difference between CRUD operations (GET, PUT and DELETE in HTTP) and non-CRUD operations (POST in HTTP) is the level of abstraction. It is better known as the difference between abstract data types and objects, and Alan Kay has been stressing on that difference in most of his talks and his ACM paper The Early History of Smalltalk (emphasis mine):

What I got from Simula was that you could now replace bindings and assignments with goals. The last thing you wanted any programmer to do is mess with internal state even if presented figuratively. Instead, the objects should be presented as sites of higher level behaviors more appropriate for use as dynamic components.

[…] It is unfortunate that much of what is called "object-oriented programming" today is simply old style programming with fancier constructs. Many programs are loaded with "assignment-style" operations now done by more expensive attached procedures.

[…] Assignment statements—even abstract ones—express very low-level goals, and more of them will be needed to get anything done. […] Another way to think of all this is: though the late-binding of automatic storage allocations doesn’t do anything a programmer can’t do, its presence leads both to simpler and more powerful code. OOP is a late binding strategy for many things and all of them together hold off fragility and size explosion much longer than the older methodologies.

04.12.2020 20:56
4
1

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.

08.05.2018 02:39
Comments
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. by Jitsusama, 02.07.2019 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.". by maaartinus, 03.07.2019 00: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. by dariok, 25.10.2019 18:18
@dariok Agreed, it'd make it even a bit worse than it already is. by maaartinus, 25.10.2019 22:51
0
1

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.
20.09.2019 13:31
0
1

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.

26.06.2019 09:01