When To Use PATCH vs. PUT in Professional REST APIs

A thumbnail showing code. Everything you need to know about using PATCH vs PUT when building professional REST APIs.

RESTful APIs are everywhere. But if you're a web development, you know it's hard to decide which HTTP request method is best for various use cases.

Updating a resource is a very common task for REST APIs and there are two HTTP request methods that developers commonly use: PUT and PATCH.

Which one should you use?

They both seem like they would do the same thing - update a resource on the server, but they do different tasks under the hood.

This guide will help you understand the difference between PUT and PATCH requests so that you can design professional production-ready APIs.

Difference between PUT and PATCH

The difference between PUT and PATCH in REST API is that PUT handles updates by replacing the entire entity, while PATCH only updates the fields that you give it.

PATCH does not change any of the other values.

If you use the PUT method, then everything will get updated. Depends on server implementation, but in most REST APIs, this means it will overwrite any missing fields to null.

PATCH method updates individual fields without overwriting existing fields.

Use HTTP PUT when you are updating an entity that you cannot separate into smaller chunks. For example, we should update an avatar image as a complete entity, rather than patching the individual pixel bits.

PUT needs more bandwidth because it handles full resources, so PATCH was introduced to reduce the bandwidth needed.

In both cases, the HTTP response code should tell you whether the update is successful.

PUTPATCH
Partial Updates✔️
Bandwidth⬆️⬇️
Creates a resource✔️
Idempotent✔️
Safe

PUT

The HTTP PUT request method is used to create a new resource or replace an old one.

The IETF has defined the HTTP PUT method as "only allowing a full replacement of a document."

The client must send a complete entity in a request body with all the new values for the resource.

  • client provides the resource ID
  • if the resource exists, replace it with the inbound data
  • if it doesn't exist, create a new one

Advantage of using PUT

  • An advantage of using PUT is that we don't have to re-fetch the entity after successfully updating it. Since PUT sends the entire entity, it'll replace whatever is there with what we send.
  • Another advantage of using PUT is that we can always overwrite the complete entity if we send down all fields and do not include any delta modification to existing fields. This means that our API clients only need to implement a single PUT method instead of many for partial updates.
  • PUT creates a resource if one doesn't exist, which can come useful.

PATCH

PATCH is used to change or add data on existing resources.

HTTP PUT method creates the entire resource at once, whereas PATCH only updates the fields that are being patched.

HTTP PATCH method was added to the HTTP protocol in 2010 to overcome the limitations of HTTP PUT request, which provides no support for partial updates.

Advantage of using PATCH

  • The client doesn't need to know the complete state of the resource before sending an update request.
  • PATCH makes it easier to keep a track of update intent to see what changed with each request. This advantage can be useful in situations where we need to review logs to debug. Noticing how resource change is easier with PATCH rather than PUT because the request body has very specific intent.
  • PATCH saves bandwidth by allowing partial updates. It is more efficient than HTTP PUT for updating large objects.

Generic Updates vs Intent

It's important to consider both client and server implementation when choosing between PATCH and PUT.

From the client's perspective, PATCH seems great because it only updates the data that you need to. But when you look at it from a server's perspective, things get complicated.

For example:

PATCH /orders/533
{
    "total": 8.34
}

In this request, we only want to update the total, meaning that server implementation should not touch other fields. However, server developers now need to know all fields that clients might update.

We call this the "intent" of the update and it's not explicit in a PATCH request.

To overcome this, we can use a feature called JSON Patch, where we define the intent of the update.

An intent represents a change you want to make of an entity. With property-based patching, you can use HTTP headers to express the intent of an update.

PATCH /orders/533
[

    { "op": "replace", "path": "/total", "value": "8.34" }

]

According to RFC6902, the supported intents are "add",  "remove", "replace", "move", "copy", or "test".

JSON Patch makes updating a resource a lot easier. The client defines the intent, and the server updates the object based on the context of that definition.

Idempotent Principle

RESTful architecture is all about idempotent operations. An idempotent operation has the same result, no matter when it is done. Non-idempotent operations can have different results.

An idempotent method's definition applies to the resource rather than the result. If you call the same idempotent method twice, the method should produce the same result both times.

An idempotent method should not have any side-effects. A side-effect is any state change outside the method itself.

PUT is idempotent but PATCH is not because of its ability to modify resource's entire content rather than specific fields.

PATCH is not, because the modified data might result in different state than if it had never been patched. PATCH should only be used when you are updating or changing data on existing resources. If you find yourself needing to create a resource and

Concurrent updates

When applying PATCH changes, it's a good idea to include a condition in the request to prevent it from succeeding if someone else updated the resource in the meantime.

The ETag HTTP response header is an ID. It is the identifier for a specific version of a resource.

When If-Match header and ETags are used in combination, they help to make sure that when a client is trying to update a resource, they can't. Instead, the old resource is kept and the new one isn't saved.

Summary - PATCH vs PUT

The Internet Engineering Task Force (IETF) is a group of people who work on how the World Wide Web should work. They have rules, but it is up to developers to follow them by adding to them into their systems.

If you have to choose between PATCH and PUT, thinking about these main differences:

  • With a PUT request, the server modifies the resource identified by the Request-URI in place. In contrast, with a PATCH request, the server replaces or updates only certain parts of a resource without changing other aspects.
  • When we execute a PUT request, we regard the enclosed entity as a modified version of the origin server's resource and the client is requesting to replace the existing version. With PATCH, however, the enclosed entity contains a set of instructions describing how to modify a resource currently on the origin server to produce a new version.

FAQ

What is the difference between PUT and PATCH?
Should I use PUT or PATCH?
Do PATCH requests have a body?
Which HTTP status code should PATCH return?
Which HTTP status code should PUT return?
Can you use both PUT and PATCH?
Is PATCH or PUT easier for the client?
Is PATCH allowed on read-only resources?
Why PUT is idempotent and PATCH is not?
Can PATCH be idempotent?
Does an idempotent method have side-effects?
Is PUT safe?
Can PATCH create a resource?
Published on