Use of PUT vs PATCH methods in REST API real life scenarios

Question

First of all, some definitions:

PUT is defined in Section 9.6 RFC 2616:

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.

PATCH is defined in RFC 5789:

The PATCH method requests that a set of changes described in the request entity be applied to the resource identified by the Request- URI.

Also according to RFC 2616 Section 9.1.2 PUT is Idempotent while PATCH is not.

Now let us take a look at a real example. When I do POST to /users with the data {username: 'skwee357', email: '[email protected]'} and the server is capable of creating a resource, it will respond with 201 and resource location (lets assume /users/1) and any next call to GET /users/1 will return {id: 1, username: 'skwee357', email: '[email protected]'}.

Now let us say I want to modify my email. Email modification is considered "a set of changes" and therefore I should PATCH /users/1 with "patch document". In my case it would be the json document: {email: '[email protected]'}. The server then returns 200 (assuming permission are ok). This brings me to first question:

• PATCH is NOT idempotent. It said so in RFC 2616 and RFC 5789. However if I issue the same PATCH request (with my new email), I will get the same resource state (with my email being modified to the requested value). Why is PATCH not then idempotent?

PATCH is a relatively new verb (RFC introduced in March 2010), and it comes to solve the problem of "patching" or modifying a set of fields. Before PATCH was introduced, everybody used PUT to update resources. But after PATCH was introduced, it leaves me confused about what PUT is used for. And this brings me to my second (and the main) question:

• What is the real difference between PUT and PATCH? I have read somewhere that PUT might be used to replace entire entity under specific resource, so one should send the full entity (instead of set of attributes as with PATCH). What is the real practical usage for such case? When would you like to replace / overwrite an entity at a specific resource URI and why is such an operation not considered updating / patching the entity? The only practical use case I see for PUT is issuing a PUT on a collection, i.e. /users to replace the entire collection. Issuing PUT on a specific entity makes no sense after PATCH was introduced. Am I wrong?

Solution 1

NOTE: When I first spent time reading about REST, idempotence was a confusing concept to try to get right. I still didn't get it quite right in my original answer, as further comments (and Jason Hoetger's answer) have shown. For a while, I have resisted updating this answer extensively, to avoid effectively plagiarizing Jason, but I'm editing it now because, well, I was asked to (in the comments).

After reading my answer, I suggest you also read Jason Hoetger's excellent answer to this question, and I will try to make my answer better without simply stealing from Jason.

Why is PUT idempotent?

As you noted in your RFC 2616 citation, PUT is considered idempotent. When you PUT a resource, these two assumptions are in play:

1. You are referring to an entity, not to a collection.

2. The entity you are supplying is complete (the entire entity).

Let's look at one of your examples.

{ "username": "skwee357", "email": "[email protected]" }

If you POST this document to /users, as you suggest, then you might get back an entity such as

## /users/1

{
    "username": "skwee357",
    "email": "[email protected]"
}

If you want to modify this entity later, you choose between PUT and PATCH. A PUT might look like this:

PUT /users/1
{
    "username": "skwee357",
    "email": "[email protected]"       // new email address
}

You can accomplish the same using PATCH. That might look like this:

PATCH /users/1
{
    "email": "[email protected]"       // new email address
}

You'll notice a difference right away between these two. The PUT included all of the parameters on this user, but PATCH only included the one that was being modified (email).

When using PUT, it is assumed that you are sending the complete entity, and that complete entity replaces any existing entity at that URI. In the above example, the PUT and PATCH accomplish the same goal: they both change this user's email address. But PUT handles it by replacing the entire entity, while PATCH only updates the fields that were supplied, leaving the others alone.

Since PUT requests include the entire entity, if you issue the same request repeatedly, it should always have the same outcome (the data you sent is now the entire data of the entity). Therefore PUT is idempotent.

Using PUT wrong

What happens if you use the above PATCH data in a PUT request?

GET /users/1
{
    "username": "skwee357",
    "email": "[email protected]"
}
PUT /users/1
{
    "email": "[email protected]"       // new email address
}

GET /users/1
{
    "email": "[email protected]"      // new email address... and nothing else!
}

(I'm assuming for the purposes of this question that the server doesn't have any specific required fields, and would allow this to happen... that may not be the case in reality.)

Since we used PUT, but only supplied email, now that's the only thing in this entity. This has resulted in data loss.

This example is here for illustrative purposes -- don't ever actually do this. This PUT request is technically idempotent, but that doesn't mean it isn't a terrible, broken idea.

How can PATCH be idempotent?

In the above example, PATCH was idempotent. You made a change, but if you made the same change again and again, it would always give back the same result: you changed the email address to the new value.

GET /users/1
{
    "username": "skwee357",
    "email": "[email protected]"
}
PATCH /users/1
{
    "email": "[email protected]"       // new email address
}

GET /users/1
{
    "username": "skwee357",
    "email": "[email protected]"       // email address was changed
}
PATCH /users/1
{
    "email": "[email protected]"       // new email address... again
}

GET /users/1
{
    "username": "skwee357",
    "email": "[email protected]"       // nothing changed since last GET
}

My original example, fixed for accuracy

I originally had examples that I thought were showing non-idempotency, but they were misleading / incorrect. I am going to keep the examples, but use them to illustrate a different thing: that multiple PATCH documents against the same entity, modifying different attributes, do not make the PATCHes non-idempotent.

Let's say that at some past time, a user was added. This is the state that you are starting from.

{
  "id": 1,
  "name": "Sam Kwee",
  "email": "[email protected]",
  "address": "123 Mockingbird Lane",
  "city": "New York",
  "state": "NY",
  "zip": "10001"
}

After a PATCH, you have a modified entity:

PATCH /users/1
{"email": "[email protected]"}

{
  "id": 1,
  "name": "Sam Kwee",
  "email": "[email protected]",    // the email changed, yay!
  "address": "123 Mockingbird Lane",
  "city": "New York",
  "state": "NY",
  "zip": "10001"
}

If you then repeatedly apply your PATCH, you will continue to get the same result: the email was changed to the new value. A goes in, A comes out, therefore this is idempotent.

An hour later, after you have gone to make some coffee and take a break, someone else comes along with their own PATCH. It seems the Post Office has been making some changes.

PATCH /users/1
{"zip": "12345"}

{
  "id": 1,
  "name": "Sam Kwee",
  "email": "[email protected]",  // still the new email you set
  "address": "123 Mockingbird Lane",
  "city": "New York",
  "state": "NY",
  "zip": "12345"                      // and this change as well
}

Since this PATCH from the post office doesn't concern itself with email, only zip code, if it is repeatedly applied, it will also get the same result: the zip code is set to the new value. A goes in, A comes out, therefore this is also idempotent.

The next day, you decide to send your PATCH again.

PATCH /users/1
{"email": "[email protected]"}

{
  "id": 1,
  "name": "Sam Kwee",
  "email": "[email protected]",
  "address": "123 Mockingbird Lane",
  "city": "New York",
  "state": "NY",
  "zip": "12345"
}

Your patch has the same effect it had yesterday: it set the email address. A went in, A came out, therefore this is idempotent as well.

What I got wrong in my original answer

I want to draw an important distinction (something I got wrong in my original answer). Many servers will respond to your REST requests by sending back the new entity state, with your modifications (if any). So, when you get this response back, it is different from the one you got back yesterday, because the zip code is not the one you received last time. However, your request was not concerned with the zip code, only with the email. So your PATCH document is still idempotent - the email you sent in PATCH is now the email address on the entity.

So when is PATCH not idempotent, then?

For a full treatment of this question, I again refer you to Jason Hoetger's answer which already fully answers that.

Solution 2

Though Dan Lowe's excellent answer very thoroughly answered the OP's question about the difference between PUT and PATCH, its answer to the question of why PATCH is not idempotent is not quite correct.

To show why PATCH isn't idempotent, it helps to start with the definition of idempotence (from Wikipedia):

The term idempotent is used more comprehensively to describe an operation that will produce the same results if executed once or multiple times [...] An idempotent function is one that has the property f(f(x)) = f(x) for any value x.

In more accessible language, an idempotent PATCH could be defined as: After PATCHing a resource with a patch document, all subsequent PATCH calls to the same resource with the same patch document will not change the resource.

Conversely, a non-idempotent operation is one where f(f(x)) != f(x), which for PATCH could be stated as: After PATCHing a resource with a patch document, subsequent PATCH calls to the same resource with the same patch document do change the resource.

To illustrate a non-idempotent PATCH, suppose there is a /users resource, and suppose that calling GET /users returns a list of users, currently:

[{ "id": 1, "username": "firstuser", "email": "[email protected]" }]

Rather than PATCHing /users/{id}, as in the OP's example, suppose the server allows PATCHing /users. Let's issue this PATCH request:

PATCH /users
[{ "op": "add", "username": "newuser", "email": "[email protected]" }]

Our patch document instructs the server to add a new user called newuser to the list of users. After calling this the first time, GET /users would return:

[{ "id": 1, "username": "firstuser", "email": "[email protected]" },
 { "id": 2, "username": "newuser", "email": "[email protected]" }]

Now, if we issue the exact same PATCH request as above, what happens? (For the sake of this example, let's assume that the /users resource allows duplicate usernames.) The "op" is "add", so a new user is added to the list, and a subsequent GET /users returns:

[{ "id": 1, "username": "firstuser", "email": "[email protected]" },
 { "id": 2, "username": "newuser", "email": "[email protected]" },
 { "id": 3, "username": "newuser", "email": "[email protected]" }]

The /users resource has changed again, even though we issued the exact same PATCH against the exact same endpoint. If our PATCH is f(x), f(f(x)) is not the same as f(x), and therefore, this particular PATCH is not idempotent.

Although PATCH isn't guaranteed to be idempotent, there's nothing in the PATCH specification to prevent you from making all PATCH operations on your particular server idempotent. RFC 5789 even anticipates advantages from idempotent PATCH requests:

A PATCH request can be issued in such a way as to be idempotent, which also helps prevent bad outcomes from collisions between two PATCH requests on the same resource in a similar time frame.

In Dan's example, his PATCH operation is, in fact, idempotent. In that example, the /users/1 entity changed between our PATCH requests, but not because of our PATCH requests; it was actually the Post Office's different patch document that caused the zip code to change. The Post Office's different PATCH is a different operation; if our PATCH is f(x), the Post Office's PATCH is g(x). Idempotence states that f(f(f(x))) = f(x), but makes no guarantes about f(g(f(x))).

Solution 3

TLDR - Dumbed Down Version

PUT => Set all new attributes for an existing resource.

PATCH => Partially update an existing resource (not all attributes required).

Solution 4

I was curious about this as well and found a few interesting articles. I may not answer your question to its full extent, but this at least provides some more information.

http://restful-api-design.readthedocs.org/en/latest/methods.html

The HTTP RFC specifies that PUT must take a full new resource representation as the request entity. This means that if for example only certain attributes are provided, those should be remove (i.e. set to null).

Given that, then a PUT should send the entire object. For instance,

/users/1
PUT {id: 1, username: 'skwee357', email: '[email protected]'}

This would effectively update the email. The reason PUT may not be too effective is that your only really modifying one field and including the username is kind of useless. The next example shows the difference.

/users/1
PUT {id: 1, email: '[email protected]'}

Now, if the PUT was designed according the spec, then the PUT would set the username to null and you would get the following back.

{id: 1, username: null, email: '[email protected]'}

When you use a PATCH, you only update the field you specify and leave the rest alone as in your example.

The following take on the PATCH is a little different than I have never seen before.

http://williamdurand.fr/2014/02/14/please-do-not-patch-like-an-idiot/

The difference between the PUT and PATCH requests is reflected in the way the server processes the enclosed entity to modify the resource identified by the Request-URI. In a PUT request, the enclosed entity is considered to be a modified version of the resource stored on the origin server, and the client is requesting that the stored version be replaced. With PATCH, however, the enclosed entity contains a set of instructions describing how a resource currently residing on the origin server should be modified to produce a new version. The PATCH method affects the resource identified by the Request-URI, and it also MAY have side effects on other resources; i.e., new resources may be created, or existing ones modified, by the application of a PATCH.

PATCH /users/123

[
    { "op": "replace", "path": "/email", "value": "[email protected]" }
]

You are more or less treating the PATCH as a way to update a field. So instead of sending over the partial object, you're sending over the operation. i.e. Replace email with value.

The article ends with this.

It is worth mentioning that PATCH is not really designed for truly REST APIs, as Fielding's dissertation does not define any way to partially modify resources. But, Roy Fielding himself said that PATCH was something [he] created for the initial HTTP/1.1 proposal because partial PUT is never RESTful. Sure you are not transferring a complete representation, but REST does not require representations to be complete anyway.

Now, I don't know if I particularly agree with the article as many commentators point out. Sending over a partial representation can easily be a description of the changes.

For me, I am mixed on using PATCH. For the most part, I will treat PUT as a PATCH since the only real difference I have noticed so far is that PUT "should" set missing values to null. It may not be the 'most correct' way to do it, but good luck coding perfect.

Solution 5

tl;dr version

• POST: is used to create an entity

• PUT: is used to update/replace an existing entity where you must send the entire representation of the entity as you wish for it to be stored

• PATCH: is used to update an entity where you send only the fields that need to be updated

View more solutions

Comments

[Julian Reschke]

a) it's RFC 2616, not 2612. b) RFC 2616 has been obsoleted, the current spec of PUT is in greenbytes.de/tech/webdav/rfc7231.html#PUT, c) I don't get your question; isn't it pretty obvious that PUT can be used to replace any resource, not only a collection, d) before PATCH was introduced, people usually used POST, e) finally, yes, a specific PATCH request (depending on the patch format) can be idempotent; it's just that it's not generally.

[equivalent8]

if it helps I've wrote an article on the PATCH vs PUT eq8.eu/blogs/36-patch-vs-put-and-the-patch-json-syntax-war

[Tom Russell]

Simple: POST creates an item in a collection. PUT replaces an item. PATCH modifies an item. When POSTing, the URL for the new item is computed and returned in the response, whereas PUT and PATCH require a URL in the request. Right?

[Daniel]

datatracker.ietf.org/doc/html/rfc5789#section-2 PATCH is not idempotent.

[theking2]

@equivalent8 the link no longer points to the article, I'm afraid

[equivalent8]

sorry @theking2 the url has changed it suppose to be blog.eq8.eu/article/put-vs-patch.html

[Johannes Brodwall]

It may be worth adding: in William Durand's article (and rfc 6902) there are examples where "op" is "add". This is obviously not idempotent.

[Jason Hoetger]

This sentence isn't quite correct: "But it is idempotent: whenever A goes in, B always comes out". For example, if you were to GET /users/1 before the Post Office updated the zip code and then again make the same GET /users/1 request after the Post Office's update, you would get two different responses (different zip codes). The same "A" (GET request) is going in, but you're getting different results. Yet GET is still idempotent.

[Dan Lowe]

@JasonHoetger GET is safe (presumed to cause no change), but is not always idempotent. There is a difference. See RFC 2616 sec. 9.1.

[Jason Hoetger]

@DanLowe: GET most definitely is guaranteed to be idempotent. It says exactly that in Section 9.1.2 of RFC 2616, and in the updated spec, RFC 7231 section 4.2.2, that "Of the request methods defined by this specification, PUT, DELETE, and safe request methods are idempotent." Idempotence just doesn't mean "you get the same response every time you make the same request". 7231 4.2.2 goes on to say: "Repeating the request will have the same intended effect, even if the original request succeeded, though the response might differ."

[Dan Lowe]

@JasonHoetger I'll concede that, but I don't see what it has to do with this answer, which discussed PUT and PATCH and never even mentions GET...

[Jason Hoetger]

@DanLowe: My point was that the definition of idempotence in your answer was incorrect, and that the PATCH in your example is actually idempotent. I added an answer that includes an example of a non-idempotent PATCH.

[Dan Lowe]

@JasonHoetger I suppose it depends what result you are considering. Your point is that the overall state isn't changed as a result of the patch, whereas I was demonstrating the returned result differs between one request and a later request.

[Ashish K Agarwal]

@DanLowe Very nicely explained !

[alexrussell]

I agree with @JasonHoetger here - Dan's answer is certainly 'nice' and has some nice examples. But, ultimately, it is completely incorrect in terms of answering the question and its definition of idempotent.

[Zach]

Can this answer please be updated to remove or alter the statements like "it is idempotent: whenever A goes in, B always comes out." As others have pointed out these statements can be reasonably construed as an attempt to define "idempotent" in the context of a RESTful API. When taken as an attempt to define, this statement is simply incorrect (idempotence makes claims about input repetition, the definition shows a relationship to outputs that is not guaranteed). This is the top answer on a highly visible question. It is teaching newcomers to REST the incorrect definition of an important term.

[Zach]

@DanLowe - I think this is great! 1000 hats off to you for having the humility to update the answer.

[Uzair Sajid]

Assuming that the server also allows issuing PUT at /users, this would make PUT non-idempotent as well. All this comes down to is how the server is designed to handle requests.

[Jason Hoetger]

@UzairSajid - PATCH and PUT are independent. Issuing a PUT to /users should always be idempotent, and if it is not, the server is non-compliant.

[niico]

"This PUT request is technically idempotent" - yes but it's sending the wrong data (ie missing data) that's the point. Good piece.

[bohr]

So, We could build an API only with PATCH operations. Then, what becomes the REST principle of using http VERBS to make CRUD actions on Resources ? Aren't we overcomplexifying the PATCH borders gentlemen here ?

[Piotr Kula]

Or you can make easier and use the RFC 7396 Merge Patch instead and avoid building patch JSON.

[stackdave]

for nosql tables, differences between patch and put is important, because nosql have no columns

[Vectorjohn]

If PUT is implemented on a collection (e.g. /users), any PUT request should replace the contents of that collection. So a PUT to /users should expect a collection of users and delete all others. This is idempotent. It isn't likely you'd do such a thing on a /users endpoint. But something like /users/1/emails may be a collection and it may be perfectly valid to allow replacing the entire collection with a new one.

[Mladen B.]

What I think is that most people are making a mistake thinking that PUT/PATCH applies to the response somehow, when it actually applies to the request. What you are stating using the idempotent PUT method (a=5) is that your request can be repeated numerous times, having the same (constant) state change applied to the resource. If you use the non-idempotent PATCH method (a=a+5), you state that your request for change is of a dynamic nature and it matters how many times you perform it.

[Mladen B.]

The typical example for PUT/PATCH difference is when you buy something on ebay for example and after clicking the buy button the page doesn't refresh, so what do you do? Clicking the buy button again would do what exactly? Will it just re-commit the same purchasing transaction (PUT) or will it buy another item (POST/PATCH). Looking at the method used, when the buy button is clicked, should answer this question.

[ivandov]

Though this answer provides a great example of idempotence, I believe this may muddy the waters in typical REST scenarios. In this case you have a PATCH request with an additional op action that is triggering specific server side logic. This would require server and client to be aware of the specific values to pass for the op field to trigger server side workflows. In more straightforward REST scenarios, this type of op functionality is bad practice and should likely be handled directly through HTTP verbs.

[Tom Russell]

2 different requests updating different attributes is given to show that PATCH is indeed idempotent? Doesn't idempotent mean the same request?

[Tom Russell]

Ah, the comment from @JasonHoetger cleared it up: only the resulting states, rather than responses, of multiple idempotent method requests need be identical.

[Tom Russell]

I would never consider issuing a PATCH, only POST and DELETE, against a collection. Is this really ever done? Can PATCH therefore be considered idempotent for all practical purposes?

[Tom Russell]

Perhaps my last comment reiterated at least part of the very informative one by @ivandov

[Rolvernew]

I don't think relying on Wikipedia's mathematical definition of idempotence helps a lot here (although I love mathematics). The RFC defines idempotence in a much more pragmatic way, see my answer below.

[ozanmuyes]

Totally agree with @bohr here, PATCH can easily be abused. I suggest to read the article Please. Don't Patch Like An Idiot. by William Durand and the RFC 7396. Sadly HTTP is a giant mess and REST on top of it doesn't make it bearable.

[DFSFOT]

But why would you use PATCH to add a user to the users collection? You're basically creating a new resource (new user), shouldn't that be done with a POST request? This confuses me.

[Arthur Khazbs]

@DFSFOT It makes sense only if the collection itself (e.g. users) is considered a resource/entity

[NFerocious]

PATCH /api/v1/users/change_pw 204 93.520 ms - - PATCH /api/v1/users/change_pw 204 82.513 ms - - PATCH /api/v1/users/change_pw 204 80.690 ms - - PATCH /api/v1/users/change_pw 204 79.999 ms - - PUT /api/v1/users/change_pw 204 1.194 ms - - PUT /api/v1/users/change_pw 204 0.382 ms - - PUT /api/v1/users/change_pw 204 0.332 ms - - PUT /api/v1/users/change_pw 204 0.350 ms - - PUT /api/v1/users/change_pw 204 0.349 ms - - PUT /api/v1/users/change_pw 204 0.326 ms - - and also the speed... but it won't actually matter since it is very small

[wulftone]

This example doesn't really follow proper RESTful semantics. The collection wouldn't be appended to with either a PATCH or a PUT, but a POST. The demonstrated PATCH /users [{ "op": "add", ... operation is really a POST /users in disguise. I would re-design this API and avoid anything resembling RPC-in-JSON semantics.

[Jonas Kölker]

Note that if you're modifying something with a fixed set of fields/members/part/columns, modifying a single field/etc. is idempotent: it's override a whole thing (inside a thing) with a new whole thing. The problem comes with collections that can have a varying number of members. Operations that add a new member can never be idempotent, and operations that increment an integer (such as the collection's size) can likewise never be idempotent: if f(x) = x + c and f(f(x)) = f(x) then (x+c)+c = x+c so c=0. TL;DR: maps, tuples and records can be okay, array(List)s and std::vector cannot.

[Jose V]

Additionally: PATCH => could be instructions rather than just the updated properties

[Manav Bokinala]

Another example of a non-idempotent PATCH is when storing how many points a user has. For example, if this was the original document: {"username": "bob", "points": 3}, and you wanted to increase his score by 2, there are two approaches: with a PATCH, you might do something like this: {"points": {"op": "add", "amount": 2}. This is NOT idempotent since if you do the same patch again, the score will change from 5 to 7. An idempotent version using PUT would be the following: {"username": "bob", "points": 5}. No matter how many times you run this, the score will be 5.

[jossefaz]

Why is it important to send ALL fields for an update ?

[jossefaz]

Why would we send ALL the attributes for an existing resource if the gal is simple to update ? why is it important to check that ? and not simply update fields that are sent ?

[NekoOs]

@jossefaz because you want to replace the entire resource.

[jossefaz]

So do you think that we can update your answer for the PUT to "is used to update/replace an existing entity" ?

[Bilal]

Thanks @jossefaz, I updated my answer

[Operator]

Short and to the point = just how we want it here. Should have been the accepted answer.

[Igor Donin]

HTTP Verbs concepts and definitions stand alone. REST is just an architectural style. Now, if the OP asked how to implement PATCH operations in a RESTful way, then some of these comments might make sense. The thing is just that people mix ups these concepts all the time when they are not necessarily related.

[theking2]

So is PUT a special case of a PATCH where the only difference is that PUT includes a complete set where PATCH is allowed to have a subset of a representation?

[theking2]

Thanks for the artical link. I sheds an interesting light on the HTTP PATCH and JSON-PATCH congruency