JSON Patch: The Smart Way to Update Your API Data

You've built a modern API. The GET fetches data, the POST creates new resources—smooth so far. But when it comes to updating data, things get tricky.

Say a user just wants to change their email. Do you really need them to resend the entire user profile? That's clunky, inefficient, and error-prone—especially with slow connections or conflicting updates.

There's a better way: JSON Patch.
Instead of sending the whole object, you send only the changes. Think of it like giving a tailor a list of alterations rather than remaking the whole suit.

Since JSON has become the universal language for APIs, JSON Patch offers a lightweight, elegant solution for partial updates.

Of course, designing and testing APIs with JSON Patch requires the right tools. That's where Apidog comes in. It lets you craft, test, and validate JSON Patch requests with ease—so you know your updates work as intended before writing a single line of code. Best of all, it's free to download and start experimenting with today.

Next, let's break down what JSON Patch is, how it works, and why it should be part of your next project.

The Problem: The "Blind" PUT Request

To understand why JSON Patch is so useful, we first need to understand the problem it solves. Traditionally, updating a resource in a RESTful API is done with the PUT HTTP method.

A PUT request is meant to be idempotent (making the same request multiple times has the same effect as making it once) and it typically replaces the entire resource at the target URL with the new representation provided in the request body.

Let's imagine a user profile resource:

GET /users/123

{
  "id": 123,
  "username": "johndoe",
  "email": "john.old@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "age": 30,
  "accountStatus": "active",
  "preferences": {
    "theme": "light",
    "notifications": true
  },
  "signUpDate": "2023-01-15"
}

Now, if John just wants to change his email address, a typical PUT request would look like this:

PUT /users/123

{
  "id": 123,
  "username": "johndoe",
  "email": "john.new@example.com", // The changed field
  "firstName": "John",
  "lastName": "Doe",
  "age": 30,
  "accountStatus": "active",
  "preferences": {
    "theme": "light",
    "notifications": true
  },
  "signUpDate": "2023-01-15"
}

Do you see the issue? We had to send back every single field, even though 99% of the data didn't change. This approach has several downsides:

1. Increased Bandwidth: We're sending a lot of unnecessary data over the wire. For large resources, this can be a significant performance hit, especially on mobile networks.
2. Higher Risk of Conflicts: If another process updates the age field while John is editing his email, John's PUT request could accidentally overwrite that new age with the old value he sent.
3. Complexity for the Client: The client application must first GET the entire resource, modify the specific field, and then PUT the whole thing back. It's multiple steps and requires the client to manage the entire state.

This is where the HTTP PATCH method comes to the rescue.

The Solution: Introducing HTTP PATCH and JSON Patch

The HTTP PATCH method was introduced to allow for partial modifications to a resource. Unlike PUT, which replaces the entire resource, PATCH applies a set of changes to the resource.

But there's a catch: the HTTP standard doesn't define what the format of those "changes" should be. You could invent your own. You could send something like:

{ "op": "change_email", "value": "new@example.com" }

But this would be custom, non-standard, and other developers would have to learn your specific language.

This is the gap that JSON Patch fills. JSON Patch (defined in RFC 6902) is a standardized format for specifying changes to be applied to a JSON document. It provides a clear, unambiguous language for describing exactly how a JSON document should be modified.

When you combine the HTTP PATCH method with a body formatted as a JSON Patch document, you have a powerful, standards-based way to perform partial updates.

How JSON Patch Works: The Basics

A JSON Patch document is always a JSON array. Each element in the array is an operation object. These operations are applied to the target document in order, and the entire patch is atomic, meaning if any single operation fails, the entire patch aborts, and the document is left unchanged.

Every operation object has a mandatory op member (short for "operation") that specifies the action to perform. The most common operations are add, remove, replace, move, and copy.

Let's look at the previous example of John changing his email. Using JSON Patch, the request becomes dramatically simpler:

PATCH /users/123

[
  { "op": "replace", "path": "/email", "value": "john.new@example.com" }
]

That's it! We're sending a single operation: "replace the value at the path '/email' with this new value." The request is small, clear, and intent-driven. We don't touch any other field.

Understanding the path Property

The path property is a JSON Pointer (RFC 6901), a string that uses a slash-based syntax to navigate through the JSON document to the specific value you want to manipulate.

• "/email" points to the root-level email field.
• "/preferences/theme" points to the theme field inside the preferences object.
• "/firstName" points to the firstName field.

This syntax is powerful for navigating nested JSON structures.

JSON Patch vs JSON Merge Patch

Developers often confuse JSON Patch (RFC 6902) with JSON Merge Patch (RFC 7386). Let’s clarify.

JSON Patch:

• Describes a sequence of operations.
• Very precise and allows complex updates.
• Example: replace, move, copy.

JSON Merge Patch:

• Sends a partial JSON document that merges into the original.
• Simpler, but less flexible.
• Example: { "name": "Bob" } would replace the name field.

In short:

• Use JSON Merge Patch for simple, shallow updates.
• Use JSON Patch for complex or multiple operations.

The JSON Patch Operations

Let's break down the most common operations with examples. We'll use the same user profile as our target document.

1. The add Operation

The add operation is used to insert a new value into an object or array.

Add a new property to an object:

{ "op": "add", "path": "/twitterHandle", "value": "@johndoe" }

This adds a new twitterHandle field to the user object.

Add an element to an array (at a specific index):

Imagine the user has a "hobbies" array: ["reading", "cycling"].

{ "op": "add", "path": "/hobbies/1", "value": "hiking" }

This inserts "hiking" at index 1, resulting in ["reading", "hiking", "cycling"]. To add to the end of the array, you can use /-: { "op": "add", "path": "/hobbies/-", "value": "hiking" }.

2. The remove Operation

The remove operation deletes a value at a specified location.

Remove a property from an object:

{ "op": "remove", "path": "/age" }

This removes the entire age field from the user object.

Remove an element from an array:

{ "op": "remove", "path": "/hobbies/0" }

This removes the first element (index 0) from the hobbies array.

3. The replace Operation

The replace operation is essentially a combination of remove and add at the same path. It replaces the existing value at a location with a new value. Our email example was a classic replace.

Change a user's theme preference:

{ "op": "replace", "path": "/preferences/theme", "value": "dark" }

4. The move Operation

The move operation removes a value from one location and adds it to another.

Move a value from one property to another:

{ "op": "move", "from": "/firstName", "path": "/first_name" }

This would move the value of firstName to a new property called first_name and remove the old firstName property.

5. The copy Operation

The copy operation copies a value from one location to another. The original value remains unchanged.

Create a backup of a setting:

{ "op": "copy", "from": "/preferences/theme", "path": "/backupTheme" }

This copies the current theme value to a new backupTheme field.

6. The test Operation

This is a safety feature. The test operation checks that a value at a location is equal to a specified value. If the test fails, the entire patch aborts. This is incredibly useful for preventing conflicts (optimistic locking).

Ensure no one else has changed the email before updating it:

[
  { "op": "test", "path": "/email", "value": "john.old@example.com" },
  { "op": "replace", "path": "/email", "value": "john.new@example.com" }
]

If the current email is not "john.old@example.com" (perhaps another process already changed it), the test operation fails, and the replace never happens. This ensures your update is based on the latest known state.

Why Use JSON Patch? The Benefits

1. Efficiency: The most obvious benefit. You only send the changes, significantly reducing payload size and improving performance.
2. Concurrency Control: The test operation provides a built-in mechanism for optimistic locking, helping you avoid lost updates and race conditions.
3. Atomicity: The all-or-nothing nature of a patch application ensures your data remains consistent. If the fifth operation in a ten-operation patch fails, the first four are rolled back.
4. Clarity and Intent: The request body clearly describes the intent of the change ("replace the email", "add a hobby") rather than just dumping a new state. This makes logs more readable and debugging easier.
5. Standardization: It's an IETF standard (RFC 6902). Other developers will recognize it, and many libraries and frameworks across different programming languages have built-in support for parsing and applying JSON Patch documents.

Common Pitfalls and Mistakes with JSON Patch

Even though JSON Patch is powerful, developers often run into these issues:

• Using the wrong path (JSON Pointer syntax errors).
• Forgetting required fields like value or from.
• Applying patches to non-existent paths.
• Overusing test operations incorrectly.
• Confusing JSON Patch with JSON Merge Patch.

Why APIs Use JSON Patch

APIs love JSON Patch because it’s:

• Efficient: Send only what’s changed.
• Atomic: Multiple changes in one request.
• Flexible: Supports advanced operations like move/copy.
• Standardized: Works across different systems.

For example, GitHub’s API supports JSON Patch for editing repository metadata efficiently.

JSON Patch in REST APIs

In RESTful APIs, JSON Patch is often used with the HTTP PATCH method.

PATCH vs PUT:

• PUT replaces the entire resource.
• PATCH updates part of the resource.

With JSON Patch, the Content-Type is:

application/json-patch+json

This tells the server the body contains a JSON Patch document.

JSON Patch in GraphQL and Other Protocols

While JSON Patch is primarily used in REST APIs, it also has relevance in:

• GraphQL mutations: Applying incremental updates.
• gRPC with JSON payloads: Sending structured patches.
• Event-driven architectures: Broadcasting only changes instead of full objects.

How JSON Patch Improves Efficiency

Imagine a mobile app syncing user profiles. Instead of re-uploading a 2MB JSON file for every tiny update, the app can just send a small patch request.

This means:

• Faster sync times.
• Lower mobile data usage.
• Better server performance.

Challenges and Considerations

JSON Patch is powerful, but it's not without its complexities.

1. Complex Implementation on the Server: Applying a patch correctly on the server is more complex than simply accepting a new JSON object. You need to validate each operation, handle pointers to non-existent paths appropriately, and ensure the entire sequence is applied atomically. Luckily, most modern web frameworks have libraries to handle this for you (e.g., json-patch for Node.js, jsonpatch for Python, JsonPatchDocument in .NET).
2. Potential for Errors: A malformed patch document or an invalid pointer (e.g., trying to replace a field that doesn't exist) will result in an error. Your API must handle these gracefully and return clear error messages (usually a 422 Unprocessable Entity or 400 Bad Request).
3. Not a Silver Bullet: For very simple resources, a PUT might still be simpler. JSON Patch shines when your resources are large or when you need to support complex, conditional updates.

Testing JSON Patch Endpoint with Apidog

Testing JSON Patch manually can be frustrating. This is where a sophisticated API tool becomes invaluable. Apidog, an all-in-one API development platform, can be a great saver here:

• Testing: You can easily test the PATCH endpoint in a visualized dashboard and get the response validation results.
• Documentation: You can document your PATCH endpoints within Apidog, clearly showing other team members the expected format, which improves collaboration and reduces integration bugs.

Example workflow in Apidog:

1. Create a new request.
2. Set method to PATCH.
3. Add Content-Type: application/json-patch+json.
4. Enter your JSON Patch array.
5. Send and verify results instantly.

By using Apidog, you move from guessing if your patch is correct to knowing it's built right, allowing you to confidently implement and consume JSON Patch APIs and start testing JSON Patch like a pro.

JSON Patch Best Practices

To use JSON Patch effectively:

1. Validate your JSON Patch documents before sending.
2. Use test operations when consistency matters.
3. Keep patches small for efficiency.
4. Document your API clearly when using JSON Patch.
5. Use tools like Apidog to streamline testing.

Conclusion: Embracing a More Efficient API Standard

So, what is JSON Patch?

It’s a standardized way to describe changes to JSON documents using operations like add, remove, and replace. Instead of sending full objects, you can send only the changes making your APIs more efficient, reliable, and flexible.

JSON Patch transforms the way we think about updating data over APIs. It moves us from the blunt instrument of full-document replacement to the precision of surgical changes. By embracing this standard, we build APIs that are more efficient, less prone to conflicts, and clearer in their intent.

While it requires a bit more upfront thought on the server side, the benefits for client applications and network performance are substantial. The next time you find yourself designing an update endpoint, resist the default PUT and ask yourself: "Could this be a job for PATCH?"

For developers, understanding JSON Patch is key to working with modern APIs, especially when handling partial updates. And with tools like Apidog, you can test, validate, and debug JSON Patch requests with ease.