1

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
  • 762
  • 1
  • 9
  • 39
  • 1
    Duplicate. Check this https://stackoverflow.com/questions/28459418/rest-api-put-vs-patch-with-real-life-examples – Samay Feb 12 '20 at 20:39
  • The post you comment does not answer the question I ask here. I am asking in the case where all the fields of an entity are updated, with both PUT and PATCH. What is the difference if all fields are updated with both methods? – Mr. Mars Feb 12 '20 at 22:44
  • 1
    There is no material difference. All your data fields changed. But your original question asked what was "good practice" and if you are replacing the entire content of the entity, then PUT is considered the correct HTTP method. In YOUR case, the PATCH is idempotent, but that doesn't mean it is in all circumstances. The detailed answers in the linked question still applies I believe. – Bryan Lewis Feb 13 '20 at 00:06
  • @BryanLewis 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 16:07
  • 1
    When you have this "update form" on the client side, are you actually detecting which fields are changing and specifically doing a patch just on those fields? If you're not, and your sending the entire entity over the wire, then it's really a PUT. If your code logic only sends the changes, and on occasion those changes encompass all fields of the entity, then I agree that you can just stick with PATCH for everything and no worry about dynamically changing HTTP methods. – Bryan Lewis Feb 13 '20 at 16:25
  • Great! Thank you! I thought so! And following this logic, won't there come a time when only PATCH is used instead of PUT? I don't see any reason to use PUT if PATCH is well implemented (allowing full and partial resource modifications) – Mr. Mars Feb 13 '20 at 20:13

1 Answers1

1

PUT is idempotent, PATCH is not. The fact that PUT is idempotent means that general purpose components can repeat a single request as many times as is necessary to produce a response.

PATCH, like POST, doesn't not promise idempotent semantics; so general purpose components are more tightly constrained in terms of what actions they can take on their own.

If all fields are updated, in that case both operations are idempotent, right?

A general-purpose component will have no understanding of whether or not all fields are updated. A high level heuristic is this: general purpose components understand the semantics of the HTTP headers, but not necessarily the semantics of the message bodies.

And, In this case, why is the PATCH of a complete resource not idempotent?

The implementation of PATCH can, indeed, be idempotent. But it doesn't have to be -- the semantics of PATCH requests don't promise idempotent handling, and therefore general-purpose components must not assume.

An analogy that might help: we prefer to use GET for queries, because GET is safe. However, sometimes other things (like de facto URI length limits) get in the way, and we are forced to use POST. There's absolutely no reason why we cannot produce a POST handler that is effectively read only.

But what we don't have is any mechanism that allows us to tell a general-purpose client that this particular use of POST happens to be safe.

GET is defined to be safe, and therefore every resource in the world is expected to handle it safely. POST is not defined to be safe; only some resources in the world handle a POST safely. And therefore general-purpose components cannot assume that any particular resource handles a POST request safely.

The same holds for idempotent semantics, and PUT vs POST/PATCH.

Community
  • 1
  • 1
VoiceOfUnreason
  • 52,766
  • 5
  • 49
  • 91
  • I get it. Then, imagine the following scenario. I have a CRUD of users. If I update a user's field I should use PATCH, but if I update all the fields I should use PUT? – Mr. Mars Feb 13 '20 at 08:10
  • And, In this case, why is the PATCH of a complete resource not idempotent? It is the same as a PUT. – Mr. Mars Feb 13 '20 at 08:29
  • @Mr.Mars Usually you shouldn't need to choose as the server, in a REST architecture, should and probably also will teach you all the information you need. Just take a HTML form as example where the respective form not only teaches you the respective fields the server expects but also the endpoint URI to send requests to, the media-type to marshal the input data to as well as the HTTP operation to use. Some of these might be implicitly given, such as `application/x-www-form-urlencoded` in the case of the media-type if not specified explicitely – Roman Vottner Mar 10 '20 at 11:41