Coderrob

Partial Updates with PATCH: Targeting Only What Needs to Change

Sun, 01 Sep 2024

When working with RESTful APIs, there are times when you need to update an entire resource, and other times when you only need to tweak a specific part of it.

This is where the PATCH method shines. Unlike PUT, which expects the complete resource object to be sent in the request body, PATCH is all about making targeted updates.

You provide the resource’s ID in the URL, and only the properties you want to change in the request body.

Updating Part of a Resource with PATCH

Let’s say you’ve got a customer in your API, and now you want to update their email address. Using the PATCH method, you can do just that without having to send the entire customer object back to the server.

Here’s how it works:

// PATCH /customers/{customerId}
{
  "email": "new.email@example.com"
}

In this example:

• The PATCH /customers/{customerId} URL provides the unique ID of the customer you’re targeting.
• The request body only includes the properties that should be updated.

NOTE: Never create an email with a “.” in it. It will get sent to the email without dots too. Dots don’t mean a thing to Gmail!.

This approach is efficient and keeps your updates lean. You’re only sending what needs to change, which can be particularly useful when working with large resources.

It also makes the intent of the update clear—you’re not overwriting the entire resource, just the parts that need adjustment.

Why Use PATCH?

Using PATCH is ideal for scenarios where:

• Efficiency: You want to minimize the amount of data sent over the network.
• Precision: You need to change only specific fields within a resource, rather than the whole object.
• Clarity: It’s clear from the request that you’re making a partial update rather than implying a full replacement with PUT.

For example, if your resource includes fields like id, name, email, and status, but you only need to modify the email, PATCH lets you do just that.

The server processes the request and updates only the specified fields, leaving everything else untouched.

PUT vs. PATCH: When to Use Each

To recap:

• Use PUT when you want to update most or all the fields of a resource. This is useful when you’re making a comprehensive update or when the entire object needs to be reset.

  PUT /customers/{customerId}
  

  Request Body (replaces the entire customer object):

  // PUT /customers/12345 HTTP/1.1
  {
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "status": "active"
  }
  

• Use PATCH when you only want to update specific fields. This is perfect for incremental changes, like updating a customer’s email address or status without touching the rest of the data.

  PATCH /customers/{customerId}
  

  Request Body (updates only the email field):

  // PATCH /customers/12345 HTTP/1.1
  {
    "active": "inactive"
  }
  

Wrapping Up PATCH Usage

By understanding and utilizing PATCH, you can extend your API creating more efficient and focused endpoints. Whether you’re updating a customer’s email, status, or any other details. The less data you have to send or receive just makes things faster.

PATCH gives you the power to make those changes precisely where and when they’re needed, without the overhead of sending unnecessary data. At least, that’s the intent.