Using JSON Patch for Efficient Incremental Updates in HTTP APIs

Problem: Sending Whole Objects When Only a Few Fields Change

Many HTTP APIs return large JSON documents for resources such as user profiles, product catalogs, or configuration objects. When a client needs to modify just one or two fields—like updating a user's age or toggling a boolean flag—it still has to send the entire representation in a PUT or POST request. This wastes bandwidth, increases latency, and makes the payload harder to review.

Thesis: JSON Patch (RFC 6902) lets clients describe only the changes they want, reducing payload size and improving responsiveness while keeping the server logic simple.

How JSON Patch Works

A JSON Patch document is an array of operation objects. Each operation specifies op (add, remove, replace, move, copy, test), a path using JSON Pointer syntax, and optionally a value. The server applies the operations atomically to the current resource state and returns the updated representation or a 204 No Content.

Implementation Steps

1. Add a PATCH endpoint to your API router that accepts application/json-patch+json (or application/json with a custom media type).
2. Deserialize the incoming patch using a library that implements RFC 6902 (e.g., Jackson’s JsonPatch, Newtonsoft.Json’s JsonPatchDocument, or Gson with a third‑party add‑on).
3. Apply the patch to a copy of the current domain model. Most libraries provide an apply method that throws if an operation is invalid (e.g., wrong path type).
4. Validate business rules** after applying the patch. If validation fails, return 400 or 409 with a helpful message.
5. Persist the updated model** and return either the full resource (200) or 204 No Content, depending on your API design.

Worked Example: Updating a User’s Age

Assume a user profile resource:

{
  "id": 123,
  "name": "Ada",
  "email": "[contact removed]",
  "age": 30
}

The client wants to change only the age to 31. The JSON Patch document is:

[
  { "op": "replace", "path": "/age", "value": 31 }
]

To send this patch from a terminal (requires only network access and a valid auth token):

curl -X PATCH https://api.example.com/users/123 \
  -H "Content-Type: application/json-patch+json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '[{ "op": "replace", "path": "/age", "value": 31 }]' \
  -i

Where to run: any shell with curl installed. Permissions: the token must grant PATCH on the user resource. Expected checks: look for a 200 (with the updated JSON) or 204 response. A 400 indicates a malformed patch (e.g., wrong path or missing value). Risks: if the patch is malformed the server will reject it; if concurrent updates occur without a concurrency check, the later patch may overwrite earlier changes.

Trade‑offs and Limitations

• Operational overhead: clients must compute correct JSON Pointer paths and, if needed, include a test operation to guard against lost updates.
• Concurrency control: JSON Patch does not provide built‑in locking; combine it with ETags, If‑Match headers, or the test operation to detect conflicts.
• Complex transactions: multi‑step business logic that depends on intermediate states may be better expressed with a custom command or a POST to a sub‑resource rather than a series of low‑level patches.

Verification Approach

Unit‑test the PATCH handler by feeding a known patch to the library’s apply method and asserting that the resulting object matches the expected JSON. For example, using Jackson:

JsonPatch patch = JsonPatch.fromJson(
    "[{ \"op\": \"replace\", \"path\": \"/age\", \"value\": 31 }]");
User user = new User(123, "Ada", "[contact removed]", 30);
patch.apply(user);
assertEquals(31, user.getAge());

Integration‑test with a tool like Postman or curl: send the patch, then GET the resource and confirm the age field changed while other fields remain unchanged.

Actionable Closing

If your API frequently handles small updates to large JSON resources, add a PATCH endpoint that accepts JSON Patch documents. Start with the replace operation, add test for optimistic concurrency, and verify with both unit and integration tests. This approach cuts bandwidth, speeds up client rendering, and keeps the server side straightforward—provided you pair it with a proper concurrency strategy.