PUT & PATCH: Knowing when to use which in building RESTful APIs
PUT replaces an entire resource, while PATCH tweaks just the parts you want.
Modern web applications are literally built on APIs, but designing them well comes down to making the right choices in small details. One of the most common points of confusion is knowing when to use PUT or PATCH when working with RESTful APIs.
At first glance, both methods seem to do the same thing (update a resource), but in reality, they follow very different rules. Understanding these differences doesn't just make your APIs cleaner and more predictable, but it also helps clients interact with them more efficiently.
In this guide, we’ll unpack what makes these two HTTP Methods different and when to use one over the other.
Oyinebiladou Omemu
HTTP and RESTful API
APIs use HTTP (Hypertext Transfer Protocol), which is basically the principle for how clients (like browsers or Postman) talk to servers. Every time you fetch a webpage or call an API, you’re sending an HTTP request and getting an HTTP response back.
RESTful APIs build on this by using standard HTTP methods: GET, POST, PUT, PATCH, DELETE, to interact with resources. GET fetches, POST creates, PUT replaces, PATCH modifies, and DELETE, as the name implies, deletes. It's pretty straightforward, but the nuances between PUT and PATCH often confuse a lot of developers, even well-grounded devs.
The Core Idea of PUT and PATCH
Again, HTTP methods are relatively simple. PUT replaces a resource with a new version of it, while PATCH modifies only part of a resource.
If you have a user profile with a name, email, and password, with PUT, you’d send all three fields (even if only the email changed), because PUT takes the full updated object and overwrites what’s there. Now, with PATCH, you’d just send { "email": "new@email.com" }, and the server updates only that field.
But that’s just the surface-level difference. The real distinction runs deeper into idempotency.
The Idempotency Factor
Both as an adjective and a noun, idempotency means the same thing. An operation is said to be idempotent if running it multiple times has the same effect as running it once.
By default, PUT is idempotent. If you call PUT /users/1 { "age": 25 } once, the user’s age is set to 25. If you call that endpoint again, nothing changes; it’s still 25. Same effect, no extra side effects.
PATCH, on the other hand, may not be idempotent. If you have PATCH /users/1/increase-age/, the first call changes age from 24 to 25. Call it again, and it becomes 26. Every request changes the state differently.
If you mistakenly use PATCH for a full replacement when the expectation is idempotency, repeated requests could produce inconsistent states. Similarly, using PUT where a partial update is intended can unintentionally wipe out fields that weren’t included in the request.
When should you use PUT or PATCH?
PUT METHOD
As a rule of thumb, use PUT when you want a predictable, idempotent update. If your API design expects clients to always send the full representation of a resource (whether or not every field has changed), PUT is the right method to use. You can use the PUT method in the following instances:
- Updating a user profile: If a user edits their account details, like name, email, and phone number, the client should send the entire profile object, even if only the email changed. The old version is fully replaced with the new one.
- Replacing a document: When updating a policy document in a database, the old document is discarded and replaced by the new version you send in full.
- Resetting settings: If a device or app allows a user to “reset configuration,” a PUT request would be used to replace the entire settings object with the default values.
PATCH METHOD
PATCH is best when only a part of the resource needs to change, when efficiency is important, or when the update is not strictly idempotent. You can use the PATCH method in the following instances:
- Updating a single field in a profile: If a user only wants to change their profile picture, PATCH allows you to send just { "profile_picture": "new.jpg" } without resending the whole profile.
- Incrementing counters: If an article has a views count, PATCH lets you update just that field (views +1) without touching other properties.
- Toggling states: For example, marking a task as {completed: true} in a to-do app without re-sending the entire task object.
- Appending data: If a user adds a new phone number to their account, PATCH allows you to just add that new entry instead of replacing the whole contact list.
Conclusion
At the end of the day, PUT and PATCH both answer how you can update a resource, but the difference lies in how much you send, and whether you want your request to be idempotent. PUT replaces the whole thing, while PATCH changes just certain parts.
When you’re designing an endpoint, think about what guarantees you want. If predictability and consistency matter, go with PUT. If efficiency and flexibility are key, reach for PATCH.
