What is the Difference Between PUT and PATCH?

Last Updated Aug 17, 2021
Emma Jagger

Engineer, maker, Google alumna, CMU grad

PUT and PATCH are both REST API requests. REST APIs perform specific methods of data operations across HTTP:

  • GET - This operation reads information from a record in the database.  
  • PUT- This operation changes a record's information in the database.  
  • POST - This operation creates a new record in the database.  
  • PATCH - This operation updates an existing resource, but does not require sending the entire body with the request.
  •  DELETE - This operation removes a record from the database.  

PUT and PATCH both perform modifications on existing data, but they do so differently because of idempotency. PUT modifies a record's information and creates a new record if one is not available, and PATCH updates a resource without sending the entire body in the request. If you're wondering how the POST request factors into this, see What's the Difference Between PUT and POST?.

A programmer should know the differences between the HTTP PUT and HTTP PATCH. PUT updates a resource, while PATCH sends a set of instructions to the URI to update the child resource. Changing records inappropriately can have unforeseen consequences for your web application!

What is a PUT request?

In the words of the RFC2616 memo: "The PUT method 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. If a new resource is created, the origin server MUST inform the user agent via the 201 (Created) response."

The PUT method modifies an existing resource or creates a new resource, and does so in an idempotent manner, which differentiates it from POST.

Use PUT

Let's say you change your email address in your Slack profile. When you update the existing record, this is a PUT request.

A PUT request might look like this: `PUT https://www.abstractapi.com/users/{{userID}}`. This would send data to the `/users/{{userID}}` endpoint, and update that user's information, and if there is no content at that URI, create a new record.

The successful response should be HTTP response code `200 OK` or `201 (created)` (https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT).

What is a PATCH Request?  

In the words of the RFC2028 memo, "The PATCH method is similar to PUT except that the entity contains a list of differences between the original version of the resource identified by the Request-URI and the desired content of the resource after the PATCH action has been applied."

What this means is a PATCH request updates an existing resource, but only the changed elements in that resource.

Using PATCH

A PATCH request sends data to an API to update resources. PATCH is like a single field in a contact form on a website. When you fill out a single field and hit Send, that data is put in the response body of the request and sent to the server. This may be JSON, XML, or query parameters.  

A PATCH request might look like this: `PATCH https://www.abstractapi.com/users/{{userID}}`. This would send data to the `/users/{{userID}}` endpoint, and update the user's information that has changed from the old version of the record.

A successful PATCH request should return a `2xx` status code, and PATCH requests should fail if invalid data is supplied in the request.

PUT vs PATCH?

The difference between PUT and PATCH is that PUT is idempotent: calling it once or several times successively has the same effect, whereas successive identical PATCH requests may have additional effects, akin to placing an order several times.  

PATCH contains instructions on how to update a resource, not the entire resource itself (as PUT and POST do). Also, not all servers support PATCH. A server advertises its support by adding it to the list in the `Allow` or `Access-Control-Allow-Methods` response headers.

How is PATCH Different from POST?

PATCH is used less frequently than POST. PATCH applies only partial modification to a resource, unlike POST and PUT, which modify the entire resource. PATCH is non-idempotent, while PUT is idempotent.  PATCH can save you some bandwidth, as updating a field with PATCH means less data being transferred than sending the whole record with PUT.

Using the `PATCH https://www.abstractapi.com/users/{{userID}}` example from above, if a user wanted to change their username, a POST or PUT request would send the entire new version, while PATCH would send instructions to overwrite the changed username.  

Conclusion

PUT is more commonly used than PATCH, as not all servers accept PATCH. PATCH requests can also have unexpected results, because they supply instructions to modify a record, and are partial updates, not full replacement of a record like a PUT request.

Becoming confident in request methods is an important step in your programming journey. They might seem a little confusing in the beginning, but knowing when to use a POST, a PUT, or a PATCH will make you use resources more efficiently. You might not need to understand the deep mathematical complexities of idempotence, but it's important to know how you are modifying a record with POST, PUT, or PATCH.

Related articles

No items found.
Start using one of Abstract's 10+ API's for free today
Get started