Building REST services require careful consideration when choosing HTTP verbs. In this post, we will take a look at the difference between HTTP PUT vs HTTP PATCH in a REST API.



When working on the REST API design, it’s always confusing when we want to choose between PUT and PATCH. To explain it in simple words, use PUT when we need to replace an existing Resource entirely, For a partial update, we can use HTTP PATCH. Let’s take an example where we only want to update customer first name and last name using our REST services, HTTP PATCH fits perfectly for this use case. HTTP PUT fits in to use case where we want to replace the entire customer profile with new information.

Another important aspect while choosing the HTTP verb is idempotence.PUT is idempotent while PATCH can and can not be (Not required).


2. Customer Data Model

Before we get into details for the HTTP PUT vs HTTP POST, let’s define out sample customer data model which will be used throughout this post.

   "email":"[email protected]"


3. Why PUT is Idempotent

While using HTTP PUT request, there are two main assumptions in this process

  • Resource mentioned in the PUT request is a resource and not collection.
  • Information or entity values supplied in the PUT request is always complete.

Let’s take an example where we want to update customer profile using PUT request. As mentioned earlier, Use PUT when we want to replace Customer resource entirely.

PUT /customers/1
  "email":"[email protected]"   //new email ID

When using PUT, we assume that complete entity is sent as part of the PUT request. In the above example, only email id was changed but request still contains the data for the complete entity. Since PUT requests include the entire entity, if you issue the same request repeatedly, it should always have the same outcome. Therefore PUT is idempotent.


3. Why PATCH is Not Required to be Idempotent

Let’s take a deeper look at why PATCH is not required to be Idempotent. We will take two examples to understand it more clearly. A PATCH request can be idempotent, but it isn’t required to be.


3.1 Idempotent PATCH

We will example of our customer data model to update email ID using HTTP PATCH 

PATCH /customers/1{  
   "email":"[email protected]"
}GET Request{  
   "last Name":"last",
   "email":"[email protected]"

In above case, if we run our PATCH request multiple times, we will get same results everytime (PATCH is Idempotent in this case).


3.2 Non Idempotent PATCH

To understand PATCH in non Idempotent mode, let’s take an example where suppose the server allows PATCHing /users. Let’s issue this PATCH request.

PATCH /customer
  "email":"[email protected]" 

if we issue the exact same PATCH request as above, a duplicate entity gets created into the system (/Customer resource changed), even though we send the same PATCH request. (PATCH is not Idempotent in this case).


4. PUT and PATCH Example

We will take same customer data model to showcase example for PUT and PATCH.

public class Customer {
    private Integer id;
    private String firstName;
    private String lastName;
    private String email;
//Put example
public class RESTController {

 private CustomerService customerService;

 public ResponseEntity < ? > saveResource(@RequestBody Customer customer,
  @PathVariable("id") String id) {
  Customer newCustomer = customerService.saveCustomer(customer, id);
  return new ResponseEntity < > (newCustomer, HttpStatus.OK);

HTTP Patch request example

public ResponseEntity < ? > updateResource(@RequestParam("email") String email, @PathVariable("id") String id) {
 Customer newCustomer = customerService.updateCustomer(email, id);
 return new ResponseEntity < > (newCustomer, HttpStatus.OK);



In this post, we explored the difference between HTTP PUT vs HTTP PATCH in a REST API. Having a clear distinction between different HTTP method while designing REST API is really important and this becomes more complex when choosing between PUT and PATCH in Spring based REST API.

The implementation of all these examples and code snippets can be found in the GitHub.

Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments