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   skwee357 domain com   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   skwee357 domain com     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   skwee357 newdomain com    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

User · Answer

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.

User · Answer

TLDR - Dumbed Down Version  PUT    Set all new attributes for an existing resource   PATCH    Partially update an existing resource  not all attributes required

User · Answer

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    You are referring to an entity  not to a collection  The entity you are supplying is complete  the entire entity     Let s look at one of your examples        username    skwee357    email    skwee357 domain com      If you POST this document to  users  as you suggest  then you might get back an entity such as      users 1         username    skwee357        email    skwee357 domain com      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    skwee357 gmail com           new email address     You can accomplish the same using PATCH  That might look like this   PATCH  users 1        email    skwee357 gmail com           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    skwee357 domain com    PUT  users 1        email    skwee357 gmail com           new email address    GET  users 1        email    skwee357 gmail com          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    skwee357 domain com    PATCH  users 1        email    skwee357 gmail com           new email address    GET  users 1        username    skwee357        email    skwee357 gmail com           email address was changed   PATCH  users 1        email    skwee357 gmail com           new email address    again    GET  users 1        username    skwee357        email    skwee357 gmail com           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    skwee357 olddomain com      address    123 Mockingbird Lane      city    New York      state    NY      zip    10001      After a PATCH  you have a modified entity   PATCH  users 1   email    skwee357 newdomain com         id   1     name    Sam Kwee      email    skwee357 newdomain com         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    skwee357 newdomain com       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    skwee357 newdomain com         id   1     name    Sam Kwee      email    skwee357 newdomain com      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  I m just going to leave it at that  because I honestly don t think I can answer this part better than he already has

User · Answer

In my humble opinion  idempotence means    PUT    I send a compete resource definition  so - the resulting resource state is exactly as defined by PUT params  Each and every time I update the resource with the same PUT params - the resulting state is exactly the same     PATCH    I sent only part of the resource definition  so it might happen other users are updating this resource s OTHER parameters in a meantime  Consequently - consecutive patches with the same parameters and their values might result with different resource state  For instance   Presume an object defined as follows   CAR   - color  black   - type  sedan   - seats  5  I patch it with    color   red    The resulting object is   CAR   - color  red   - type  sedan   - seats  5  Then  some other users patches this car with    type   hatchback    so  the resulting object is   CAR   - color  red   - type  hatchback   - seats  5  Now  if I patch this object again with    color   red    the resulting object is   CAR   - color  red   - type  hatchback   - seats  5  What is DIFFERENT to what I ve got previously   This is why PATCH is not idempotent while PUT is idempotent

User · Answer

Let me quote and comment more closely the RFC 7231 section 4 2 2  already cited in earlier comments       A request method is considered  idempotent  if the intended effect on   the server of multiple identical requests with that method is the same   as the effect for a single such request   Of the request methods   defined by this specification  PUT  DELETE  and safe request methods   are idempotent                  Idempotent methods are distinguished because the request can be   repeated automatically if a communication failure occurs before the   client is able to read the server s response   For example  if a   client sends a PUT request and the underlying connection is closed   before any response is received  then the client can establish a new   connection and retry the idempotent request   It knows that repeating   the request will have the same intended effect  even if the original   request succeeded  though the response might differ    So  what should be  the same  after a repeated request of an idempotent method  Not the server state  nor the server response  but the intended effect  In particular  the method should be idempotent  from the point of view of the client   Now  I think that this point of view shows that the last example in Dan Lowe s answer  which I don t want to plagiarize here  indeed shows that a PATCH request can be non-idempotent  in a more natural way than the example in Jason Hoetger s answer    Indeed  let s make the example slightly more precise by making explicit one possible intend for the first client  Let s say that this client goes through the list of users with the project to check their emails and zip codes  He starts with user 1  notices that the zip is right but the email is wrong  He decides to correct this with a PATCH request  which is fully legitimate  and sends only   PATCH  users 1   email    skwee357 newdomain com     since this is the only correction  Now  the request fails because of some network issue and is re-submitted automatically a couple of hours later  In the meanwhile  another client has  erroneously  modified the zip of user 1  Then  sending the same PATCH request a second time does not achieve the intended effect of the client  since we end up with an incorrect zip  Hence the method is not idempotent in the sense of the RFC   If instead the client uses a PUT request to correct the email  sending to the server all properties of user 1 along with the email  his intended effect will be achieved even if the request has to be re-sent later and user 1 has been modified in the meanwhile --- since the second PUT request will overwrite all changes since the first request

User · Answer

Everyone else has answered the PUT vs PATCH   I was just going to answer what part of the title of the original question asks   quot     in REST API real life scenarios quot    In the real world  this happened to me with internet application that had a RESTful server and a relational database with a Customer table that was  quot wide quot   about 40 columns    I mistakenly used PUT but had assumed it was like a SQL Update command and had not filled out all the columns  Problems  1  Some columns were optional  so blank was valid answer   2  many columns rarely changed  3  some columns the user was not allowed to change such as time stamp of Last Purchase Date  4  one column was a free-form text  quot Comments quot  column that users diligently filled with half-page customer services comments like spouses name to ask about OR usual order  5  I was working on an internet app at time and there was worry about packet size  The disadvantage of PUT is that it forces you to send a large packet of info  all columns including the entire Comments column  even though only a few things changed  AND multi-user issue of 2  users editing the same customer simultaneously  so last one to press Update wins   The disadvantage of PATCH is that you have to keep track on the view screen side of what changed and have some intelligence to send only the parts that changed   Patch s multi-user issue is limited to editing the same column s  of same customer

User · Answer

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    firstuser example org       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    newuser example org       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    firstuser example org         id   2   username    newuser    email    newuser example org       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    firstuser example org         id   2   username    newuser    email    newuser example org         id   3   username    newuser    email    newuser example org       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

User · Answer

To conclude the discussion on the idempotency  I should note that one can define idempotency in the REST context in two ways  Let s first formalize a few things   A resource is a function with its codomain being the class of strings  In other words  a resource is a subset of String    Any  where all the keys are unique  Let s call the class of the resources Res   A REST operation on resources  is a function f x  Res  y  Res   Res  Two examples of REST operations are    PUT x  Res  y  Res   Res   x  and PATCH x  Res  y  Res   Res  which works like PATCH  a  2    a  1  b  3       a  2  b  3      This definition is specifically designed to argue about PUT and POST  and e g  doesn t make much sense on GET and POST  as it doesn t care about persistence    Now  by fixing x  Res  informatically speaking  using currying   PUT x  Res  and PATCH x  Res  are univariate functions of type Res   Res    A function g  Res   Res is called globally idempotent  when g   g    g  i e  for any y  Res  g g y     g y   Let x  Res a resource  and k   x keys  A function g   f x  is called left idempotent  when for each y  Res  we have g g y        g y     It basically means that the result should be same  if we look at the applied keys    So  PATCH x  is not globally idempotent  but is left idempotent  And left idempotency is the thing that matters here  if we patch a few keys of the resource  we want those keys to be same if we patch it again  and we don t care about the rest of the resource   And when RFC is talking about PATCH not being idempotent  it is talking about global idempotency  Well  it s good that it s not globally idempotent  otherwise it would have been a broken operation     Now  Jason Hoetger s answer is trying to demonstrate that PATCH is not even left idempotent  but it s breaking too many things to do so    First of all  PATCH is used on a set  although PATCH is defined to work on maps   dictionaries   key-value objects  If someone really wants to apply PATCH to sets  then there is a natural translation that should be used  t  Set lt T gt    Map lt T  Boolean gt   defined with x in A iff t A  x     True  Using this definition  patching is left idempotent  In the example  this translation was not used  instead  the PATCH works like a POST  First of all  why is an ID generated for the object  And when is it generated  If the object is first compared to the elements of the set  and if no matching object is found  then the ID is generated  then again the program should work differently   id  1  email   me site com   must match with  email   me site com    otherwise the program is always broken and the PATCH cannot possibly patch   If the ID is generated before checking against the set  again the program is broken    One can make examples of PUT being non-idempotent with breaking half of the things that are broken in this example    An example with generated additional features would be versioning  One may keep record of the number of changes on a single object  In this case  PUT is not idempotent  PUT  user 12  email   me site com   results in  email         version  1  the first time  and  email         version  2  the second time  Messing with the IDs  one may generate a new ID every time the object is updated  resulting in a non-idempotent PUT    All the above examples are natural examples that one may encounter     My final point is  that PATCH should not be globally idempotent  otherwise won t give you the desired effect  You want to change the email address of your user  without touching the rest of the information  and you don t want to overwrite the changes of another party accessing the same resource

User · Answer

A very nice explanation is here- https   blog segunolalive com posts restful-api-design- E2 80 94-put-vs-patch     text RFC 205789 not 20required 20to 20be 20idempotent  A Normal Payload-    House on plot 1   address   plot 1   owner   segun   type   duplex   color   green   rooms   5   kitchens   1   windows  20   PUT For Updated-    PUT request payload to update windows of House on plot 1   address   plot 1   owner   segun   type   duplex   color   green   rooms   5   kitchens   1   windows  21   Note  In above payload we are trying to update windows from 20 to 21  Now see the PATH payload-    Patch request payload to update windows on the House   windows  21   Since PATCH is not idempotent  failed requests are not automatically re-attempted on the network  Also  if a PATCH request is made to a non-existent url e g attempting to replace the front door of a non-existent building  it should simply fail without creating a new resource unlike PUT  which would create a new one using the payload  Come to think of it  it   ll be odd having a lone door at a house address

User · Answer

One additional information I just one to add is that a PATCH request use less bandwidth compared to a  PUT request  since just a part of the data is sent not the whole entity   So just use a PATCH request for updates  of  specific records  like  1-3 records  while PUT request for updating a larger amount of data   That is it   don t think too much or worry about it too much

User · Answer

The difference between PUT and PATCH is that    PUT is required to be idempotent  In order to achieve that  you have to put the entire complete resource in the request body  PATCH can be non-idempotent  Which implies it can also be idempotent in some cases  such as the cases you described    PATCH requires some  patch language  to tell the server how to modify the resource  The caller and the server need to define some  operations  such as  add    replace    delete   For example   GET  contacts 1      id   1     name    Sam Kwee      email    skwee357 olddomain com      state    NY      zip    10001     PATCH  contacts 1       operation    add    field    address    value    123 main street        operation    replace    field    email    value    abc myemail com        operation    delete    field    zip       GET  contacts 1      id   1     name    Sam Kwee      email    abc myemail com      state    NY      address    123 main street       Instead of using explicit  operation  fields  the patch language can make it implicit by defining conventions like   in the PATCH request body    The existence of a field means  replace  or  add  that field  If the value of a field is null  it means delete that field     With the above convention  the PATCH in the example can take the following form   PATCH  contacts 1      address    123 main street      email    abc myemail com      zip       Which looks more concise and user-friendly  But the users need to be aware of the underlying convention   With the operations I mentioned above  the PATCH is still idempotent  But if you define operations like   increment  or  append   you can easily see it won t be idempotent anymore

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

Examples related to json

Examples related to rest

Examples related to http

Examples related to put

Examples related to http-method