0

In a REST API, when I want to update all the properties of an entity, what is better to use in terms of good practices? PUT or PATCH? If it is better to use PATCH, why is PUT necessary? What would be the difference between the two?

If all fields are updated, in that case both operations are idempotent, right? So, what is the difference?

Mr. Mars
  • 121
  • 1
  • 6
  • 1
    Does this answer your question? [How should a REST API handle PUT requests to partially-modifiable resources?](https://softwareengineering.stackexchange.com/questions/208271/how-should-a-rest-api-handle-put-requests-to-partially-modifiable-resources) – Dan Wilson Feb 12 '20 at 23:43
  • `PATCH` specifically deals with partial data. I.e. only update the fields specified. see https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH . The same resource also adds that `PUT` is designed for whole resource replacement. – Berin Loritsch Feb 13 '20 at 00:00
  • 1
    PATCH is NOT idempotent, whereas PUT is. – Berin Loritsch Feb 13 '20 at 00:01
  • @BerinLoritsch, In this case, why is the PATCH of a complete resource not idempotent? – Mr. Mars Feb 13 '20 at 08:06
  • The HTTP spec has speaks towards the guarantees that you are communicating with your API. My question back to you is why would you want to use PATCH if you aren't allowing for partial updates? Just stick to PUT (idempotent guarantee) or POST (no idempotent guarantee). – Berin Loritsch Feb 13 '20 at 14:05
  • @BerinLoritsch Sorry, maybe I didn't express myself well. Imagine that I do allow partial modifications. Within the whole subset of partial modifications is also the modification of all the elements of an entity. That's when the case of the original question occurs. If I have an update form and modify only one property I use PATCH, but if I modify them all, do I have to use PATCH or PUT? Should I detect that case and switch from PATCH to PUT? – Mr. Mars Feb 13 '20 at 15:31
  • 1
    If that same path does partial and total updates, then you should be able to continue to use PATCH. You don't really gain a whole lot by switching PATCH to PUT. – Berin Loritsch Feb 13 '20 at 16:00
  • @BerinLoritsch Thanks for your answer. And one last thing. How do you see a PATCH allow partial and total updates? Is this usually done? Or should it prevent a PATCH from allowing a total update? Here I am asking you for an opinion. What are the good practices in relation to the use of PATCH? I hope you do not mind :) – Mr. Mars Feb 13 '20 at 16:05
  • 1
    Think of it this way: PATCH allows you to work on a subset of information. That subset can be as little as an empty JSON object (no change) or as large as every field in the JSON object. The bottom line is only the data specified in the uploaded object is modified. The purpose is to allow partial updates to an object, and I don't see any cause to force PATCH to limit to subsets that are less than 100% of the object. – Berin Loritsch Feb 13 '20 at 16:41
  • This is a really, really frequently asked question. Please make sure to use a web search. – Martin K Feb 13 '20 at 21:17
  • @MartinK If it is a very usual question on the Internet, please share a link in which it was answering this question in particular, not to the typical question you can find, which is the difference between both verbs. My question is very concrete, talks about a particular case. If I had already found it, I would not have asked this question. – Mr. Mars Feb 14 '20 at 09:48
  • You literally asked what the difference is between the two ... – Martin K Feb 14 '20 at 19:36
  • @MartinK, The question has context. In fact, that question comes after another... If you want, I'll put it another way. When all the properties of an entity are updated, what is the difference between using PUT or PATCH? – Mr. Mars Feb 15 '20 at 12:12

1 Answers1

2

My answer depends on what the intent behind the update is.

  • If the intent is to always replace the whole object: use PUT
  • If the intent is to update a part of the object: use PATCH

The fact that in this particular case, "part of the object" happens to be 100% of the object shouldn't matter. If the call you are making will be doing partial updates as well as full updates, then having a consistent endpoint simplifies the code you have to write.

However, if the call you are making will always update the entire object use PUT. That is clearer as to your intentions, and if new fields are ever added to the object you will have an appropriate error message in the client code.

PATCH makes no guarantee of being idempotent, and since the intent is to allow partial updates to an object that makes sense. It should return the whole object with the changes applied after completion though.

PUT does have a guarantee of being idempotent, and as such requires the whole object to be replaced every time. Think of PUT as an UPSERT (Update or Insert if it doesn't exist). There typically is no body in the response. (201 for create, 204 for updates, and appropriate 400 series for errors)

Berin Loritsch
  • 45,784
  • 7
  • 87
  • 160
  • 1
    Could you please elaborate on a PATCH not being idempotent? It seems to me if you sent the same PATCH request multiple times, it would yield the same result each time. I'm not understanding why a partial vs. full update determines whether it's idempotent or not. – wired_in Apr 12 '20 at 22:02
  • Furthermore, I'm not sold on PATCH being used like this. If you have a form where the user is able to modify some or all of the fields, it still seems like you should use PUT since you are allowing the edit of the entire object. PATCH should be used for specific use cases where it's clear that only a part of the object needs to be updated, not dynamically determined by whether or not the user chooses to change all or part of it. – wired_in Apr 12 '20 at 22:07