PUT vs PATCH. What to use and when?

REST (also known as RESTful) architectural style is widely used for interaction among different applications across the web. But something with it might not be clear, as it was for me. As you might guess, I was talking about the difference between when to use PUT and when I should use PATCH.

Source: https://blog.postman.com/rest-api-examples/

PUT vs PATCH.

What do they have in common?

1. PUT and PATCH are used for Updates when you are designing a classical RESTful API.
2. They both should forbid (405 Method Not Allowed) updates of the entire collection, (e.g. /orders)
3. Recommended return values on specific item updates (e.g. /orders/{id}) are 200 (OK) or 204 (No Content), 404 (Not Found) if the id is not valid or was not found.
4. PUT and PATCH are not safe operations. That means they both modify a resource state on the server. But PUT is idempotent when the PATCH is not.

Speaking simple words about idempotency, if you create or update a resource using PUT and then make that same call again, the resource is still there and still has the same state as it did with the first call. If, for instance, calling PUT on a resource increments some value over and over again within the very same resource, the call is no longer idempotent.

What’s their confusing difference?

And there is a key difference that confused me for a long time:

Let’s use this simple JSON to make everything much clearer. And let’s assume we have a next URI: /users/{id}

{
  "name": "John",
  "second_name": "Doe",
  "age": "27"
}

The PUT method should be used to update a resource completely. That means the endpoint should receive an entire resource object, with all of its fields included. If the fields were not set in the request then you might expect the server will set default values for not provided fields.

In case we want to update John’s age, we have to send the next JSON:

method: PUT, URI: /users/15

{
  "name": "John",
  "second_name": "Doe",
  "age": "35"
}

The PATCH method should be used to partially update a resource. Thus, the client should send only fields that are allowed for update and only the fields the client wants to update. This allows you to update resources not sending redundant data over the network efficiently.

So, in this case would be enough to send the following piece of data:

method: PATCH, URI: /users/15

{
  "age": "35"
}

So, the main difference between PUT and PATCH is that PUT is used for a full update of a resource, while PATCH is used for a partial update.

Yes, it turns out it was that easy, but sometimes easy problems can be quite difficult to overcome, as was the case for me recently.

And that is all 🎉! If you enjoyed this article, feel free to say hi on LinkedIn here.