REST API Resource Partial Updates: JSON Patch vs. Merge Patch

We’ve all been there: a frontend team needs to update just one field on a massive user profile object, and your current API forces them to send the entire payload back. It’s inefficient, prone to race conditions, and honestly, it’s just bad design. When you're building a REST API design choices that scale without technical debt, you eventually hit the wall where full-resource updates (PUT) aren't enough.

That’s where resource partial updates come in. You’re essentially choosing between two RFC standards: JSON Merge Patch (RFC 7396) and JSON Patch (RFC 6902). I’ve spent months debugging both in production environments, and the "right" choice depends entirely on how much control you need over your data integrity.

Understanding the Trade-offs of Resource Partial Updates

JSON Merge Patch is the "easy" button. It’s straightforward, human-readable, and maps perfectly to how most developers think about objects. You send a JSON document that represents the subset of the object you want to change. If a key is present, the server updates it; if it’s null, the server removes it.

JSON
// PATCH /users/123
{
  "email": "new-email@example.com",
  "bio": null
}

It’s simple, but it lacks precision. You can’t easily append to an array or increment a numeric value without reading the current state first. If two clients send a merge patch simultaneously, you’re at the mercy of your database’s locking strategy.

JSON Patch, on the other hand, is an operation-based format. Instead of sending the "new state," you send a list of instructions on how to transform the resource.

JSON
// PATCH /users/123
[
  { "op": "replace", "path": "/email", "value": "new-email@example.com" },
  { "op": "remove", "path": "/bio" }
]

This is significantly more powerful. Because it uses specific operations (add, remove, replace, move, copy, test), you can perform atomic updates that are much safer in high-concurrency environments. The test operation is the secret weapon here—it allows you to verify the current state of a field before applying a change, effectively preventing "lost updates" without needing heavy-handed database locks.

Why Complexity Matters for Long-Term Maintainability

When I’m evaluating REST API designs, I usually lean toward Merge Patch for 80% of use cases. It’s easier to implement, easier to test, and doesn't require a specialized parser on the client side. Most of the time, the overhead of implementing JSON Patch isn't worth the complexity for simple CRUD services.

However, if you're building a system where state transitions are complex—like a collaborative document editor or a financial ledger—Merge Patch will bite you. I once spent about two days tracking down a bug where a Merge Patch accidentally wiped out an array because the client didn't realize the server expected the full array in the request. JSON Patch would have prevented that by allowing an add operation at a specific index.

If you decide to go the JSON Patch route, keep these things in mind:

1. Validation overhead: Every operation needs to be validated against your business logic.
2. Client friction: Not all client libraries support JSON Patch natively, which might force your frontend team to write custom logic.
3. Atomicity: Ensure your backend service wraps the entire list of operations in a single database transaction.

The Verdict

Don't over-engineer your API Design just because you can. If your resource updates are simple key-value changes, stick with JSON Merge Patch. It’s clean, standard, and keeps your codebase manageable.

Reserve JSON Patch for scenarios where you need granular control over arrays, atomic counter increments, or optimistic concurrency via the test operation. I’ve found that documenting the why behind this choice in your API spec is just as important as the implementation itself. You’ll save your future self—and your teammates—a massive headache when you have to explain why a specific endpoint requires a complex array of operations instead of a simple object.

I’m still on the fence about whether we should move our entire internal catalog system to JSON Patch. While the safety is tempting, the maintenance burden of keeping our validation logic in sync with the operation list is non-trivial. Sometimes, the "worse" technical solution is the better engineering choice because it's easier for the team to reason about.

FAQ

Q: Can I support both Merge Patch and JSON Patch on the same endpoint? A: Technically yes, but I wouldn't recommend it. It confuses client developers and makes your API contract harder to version. Stick to one content type (e.g., application/merge-patch+json vs application/json-patch+json) and be consistent.

Q: Which one is faster to implement? A: Merge Patch is significantly faster. You can usually implement it by simply merging the request body into your existing model before saving. JSON Patch requires a full-blown interpreter to walk the path and apply operations safely.

Q: How do I handle errors in JSON Patch? A: Since it's a list of operations, you need to decide if you want transactional behavior (all or nothing) or partial success. Always document your error response format clearly, as the RFC allows for complex error reporting.