PUT vs PATCH REST API Methods: Which One Should You Choose?

In RESTful API design, PUT and PATCH are two HTTP methods used to update resources on the server, but the difference between PUT vs PATCH in REST APIs is in how they perform the updates and the scenarios in which each is most appropriate. Both methods are designed to modify existing data, but understanding the PUT and PATCH difference in REST API can help developers make the best choice based on the nature of the update they need to perform. In this blog post, we’ll explore the PUT and PATCH difference in REST API, focusing on the PATCH vs update REST debate, when to use each, and provide guidance on choosing the right method for different use cases.

 

 

What is PUT in REST APIs?

To understand the difference between PUT vs PATCH in REST APIs, first, we’ll need to know what PUT is in the first place. Based on Section 9.6 RFC 2616, the PUT method in REST API 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.

In other words, the PUT method is used to update an entire resource on the server. This makes PUT a more “complete” update, often used when a full replacement of the resource is necessary.

 

So, PUT is best for the following use cases: 

• Updating a complete resource (e.g., updating a user profile with all new information).
• Replacing an entire item or record.
• When the resource’s identity is clear, and its data needs to be fully refreshed.

 

In systems like Elasticsearch, idempotent operations are necessary to guarantee data consistency. For example, updating a document in Elasticsearch using PUT ensures that the same request can be repeated without unintended side effects.

 

What is PATCH in REST APIs?

Now that we’ve covered PUT in REST APIs, let’s take a look at what PATCH is in REST APIs and how it works before we compare PUT vs PATCH in REST APIs. As defined in RFC 5789, the PATCH method in REST API requests that a set of changes described in the request entity be applied to the resource identified by the Request-URI.

This aligns with the PUT vs PATCH REST API distinction, where you only send the data that needs to be modified, and the server applies those changes to the existing resource without altering the entire resource. Developers often create patches to represent these incremental changes, ensuring minimal data transfer and efficient updates.

 

That’s why the PATCH method in REST API is better suited for the following use cases: 

• Updating only a subset of fields in a resource (e.g., changing a user’s email address or phone number). A PATCH API example could involve sending just the new email, leaving other fields untouched.
• Improving performance by minimizing the data payload.
• When you want to update a resource incrementally rather than replacing it completely.
• Create patches to encapsulate specific field changes, like modifying a user’s email, without affecting unrelated data.

For platforms like headless CMS that often handle complex content structures, using PATCH for smaller updates—like modifying a single field—can reduce server load and improve performance.

With these two methods covered, you should have a decent idea of what PUT and PATCH are in REST APIs. However, before we get into the difference between PUT vs PATCH in REST APIs, we need to talk about Idempotence in these two methods.

 

Idempotence In PUT Vs Patch in REST APIs

In REST APIs, idempotence refers to the property of an operation that, when repeated multiple times with the same inputs, results in the same outcome. This means that making the same request multiple times should have the same effect on the server, regardless of how many times it is executed. This is important for ensuring stability and predictability in an API. But how is it relevant to the PUT and PATCH difference in REST API?

 

PUT Method and Idempotence

The PUT method in REST API is always idempotent because it is designed to replace the entire resource at a specified URI with the data provided in the request. In other words, if you perform a PUT request multiple times with the same resource data, the outcome will always be the same.

Why is PUT Idempotent? When you make a PUT request, you are essentially telling the server, “This is the complete and exact state I want for this resource.” Whether you issue the PUT request once or many times, the resulting resource will always be identical.

For example, consider the scenario where you update a user’s email address. If you make the same PUT request multiple times, the result will not be altered because the resource is replaced by the same data every time.

 

Example:

PUT /users/1{“username”: “john_doe”,”email”: “[email protected]”}

 

If you send this request multiple times, the result will always be the same:

{“username”: “john_doe”,”email”: “[email protected]”}

 

Even if the user’s data is already this, sending the request again does not change anything. It replaces the data with the same data, so the effect of the request remains the same regardless of how many times it is repeated. This is what makes PUT idempotent.

 

PATCH Method and Idempotence

The PATCH method in REST API, on the other hand, is generally idempotent as well, but with more flexibility. When you create patches, ensure the operations are idempotent (e.g., setting a value) to avoid unintended side effects from repeated requests. Whether PATCH is idempotent depends on the operation and the data being modified.

Why is PATCH Idempotent? For PATCH requests, idempotence means that applying the same patch multiple times will have the same result. This is true as long as the patch itself doesn’t cause additional side effects or changes when applied repeatedly. If you keep applying the same patch with the same data, the result should be unchanged after the first application.

For instance, if you are only updating a user’s email, repeatedly sending the same PATCH request will not change the result after the first time, even if the request is made several times. The user’s email will remain the same, and the state of the resource will not change.

 

PATCH API Example:

PATCH /users/1{“email”: “[email protected]”}

 

If the email was already [email protected], then applying this PATCH again will result in no change, making it idempotent.

However, PATCH can also be non-idempotent in some cases. For example, if a PATCH operation modifies a counter or adds items to a list (such as incrementing a number or appending to an array), repeated applications of the same PATCH could lead to different results. This would violate the idempotence property.

 

Non-idempotent API REST PATCH Example:

PATCH /counter/1{“increment”: 1}

 

If you apply this PATCH repeatedly, the counter will keep increasing, resulting in different values every time. This is not idempotent because the outcome changes with each application.

Now that you know the essentials, we can look at some example scenarios to better understand the difference between PUT vs PATCH in REST APIs.

 

Example Scenarios: PUT vs PATCH in REST APIs

Theory aside, let’s look at the difference between PUT and PATCH with examples, including both idempotent and non-idempotent operations.

 

Scenario 1: PUT Request – Replacing an Entire Resource

Imagine an API endpoint for managing products in an e-commerce system. You need to update all the details of a product, including its name, price, and description. This is a typical example of the HTTP method PUT vs PATCH, where PUT is used to replace the full product resource.

 

Initial Product:

GET /products/1001{“id”: 1001,”name”: “Laptop”,”price”: 999.99,”description”: “A powerful laptop.”}

 

You want to update the product’s price and description. You send a PUT request with the entire resource:

PUT Request:

PUT /products/1001{“id”: 1001,”name”: “Laptop”,”price”: 899.99,”description”: “A discounted powerful laptop.”}

 

If you make this PUT request once or multiple times, the result will always be the same. The product details will be updated to reflect the new price and description, and the same result will occur each time. This ensures the idempotent nature of PUT.

 

Result (After PUT Request):

{“id”: 1001,”name”: “Laptop”,”price”: 899.99,”description”: “A discounted powerful laptop.”}

 

Scenario 2: PATCH Request – Updating Part of a Resource

Now, let’s consider a PATCH request for updating only part of the product’s details, such as the description. PATCH API example: If you want to change the product description but not its price, PATCH is the better choice. To implement this, you would create patches containing only the fields requiring modification, such as the description in this API REST PATCH example.

 

Initial Product:

GET /products/1001{“id”: 1001,”name”: “Laptop”,”price”: 999.99,”description”: “A powerful laptop.”}

 

PATCH Request:

PATCH /products/1001{“description”: “A lightweight, powerful laptop.”}

 

When you send this PATCH request, only the description field will be updated. If you send the same PATCH request multiple times, the description will remain unchanged after the first update, making the request idempotent.

 

Result (After PATCH Request):

{“id”: 1001,”name”: “Laptop”,”price”: 999.99,”description”: “A lightweight, powerful laptop.”}

 

If you apply the same PATCH again, the product description will still be the same as it was after the first PATCH. The result is consistent, which makes PATCH idempotent in this scenario.

 

Scenario 3: PATCH Request – Non-idempotent Operation

Let’s look at a non-idempotent PATCH operation. Suppose there is an endpoint for a user’s wallet balance, and you want to increment the balance. An example difference between PUT and PATCH can be illustrated here: PATCH will add a value to the balance each time

 

Initial Wallet:

GET /users/1/wallet{“id”: 1,”balance”: 100.00}

 

PATCH Request:

PATCH /users/1/wallet{“increment”: 50.00}

 

This PATCH request will increase the wallet balance by $50. If you send this PATCH request multiple times, the balance will keep increasing with each PATCH, leading to a different result each time. This is non-idempotent because applying the same PATCH repeatedly will cause a different outcome.

 

Result (After First PATCH Request):

{“id”: 1,”balance”: 150.00}

 

Result (After Second PATCH Request):

{“id”: 1,”balance”: 200.00}

 

Here, PATCH is not idempotent because repeated requests with the same data produce different results.

 

Recap: Key Differences Between PUT Vs PATCH In REST APIs

The key difference between PUT vs PATCH in REST API is how they handle updates. PUT replaces the entire resource, so any missing fields are wiped out, which can lead to data loss. This is why developers create patches for partial updates—to avoid overwriting unchanged fields and maintain data integrity.

This makes PATCH more efficient for partial updates. A PATCH API example is that If you want to update just a user’s email, creating patches would only send the email field, unlike a PUT request that would require the entire user data.

With PUT, the full data payload is required. This means every field must be sent, and any missing fields will be erased. PATCH, however, only sends the fields that need to be updated, making it more efficient, especially for large resources with minimal changes. The PATCH method in REST API allows for more focused and smaller requests, reducing data transfer.

Both PUT and PATCH are idempotent. This means that repeating the same request will result in the same outcome. However, PUT is more predictable as it replaces the entire resource. PATCH, when used to modify only specified fields, might lead to different results depending on how updates are handled by the server.

For example, if a PATCH increments a counter, repeated requests could lead to different outcomes. Nonetheless, PATCH API operations can be designed to be idempotent as well.

In conclusion, the PUT and PATCH difference in REST API boils down to the nature of the updates: PATCH is for partial changes, while PUT is for complete resource replacement. Both are idempotent, but PATCH can be more complex.

 

Final Thoughts

Both PUT and PATCH are fundamental HTTP methods in REST API design, but they serve different purposes, which is the essence of the PUT and PATCH difference in REST API. You can significantly improve the efficiency, clarity, and functionality of your API by understanding the difference between PUT and PATCH with the examples we covered earlier in this article  By choosing the correct method (PATCH vs update REST) based on your use case, you can make your API more efficient, maintainable, and user-friendly. Always consider the nature of the update—whether it’s full or partial—along with the impact on performance and data integrity, and select the method that best aligns with your needs.