a JSON Patch service with Spring Boot

Modern APIs rarely deal with full document replacements anymore. Teams shipping microservice platforms for Australian banks, fintech startups in Sydney, or logistics companies across Melbourne and Brisbane frequently need a way to update parts of a resource without resending the whole payload. JSON Patch, defined in RFC 6902, provides a compact and standardised format for describing these changes as a list of operations. When combined with Spring Boot, it becomes a clean way to expose partial update endpoints that stay predictable under load and easy to reason about for the developers maintaining them.

The core idea is simple. A client sends an array of operations, such as add, remove, replace, move, copy, or test, each targeting a specific location inside a JSON document. The server applies them one by one and returns either the updated resource or a structured error if something failed. This approach reduces bandwidth, makes change tracking trivial, and supports atomic updates where either everything succeeds or nothing changes.

In the next sections we will walk through the relevant specification details, set up a Spring Boot project, design the controller layer, implement the service logic with the json-patch library, and cover the validation patterns that keep production traffic safe.

What RFC 6902 actually defines

The JSON Patch specification is short, but it is worth reading at least once. Each operation is a JSON object with an op field naming the action and a path field describing where to apply it. The add operation inserts a value, replace swaps an existing one, remove deletes it, move relocates a value from one path to another, copy duplicates it, and test asserts that a value matches an expected one, failing the whole patch otherwise.

The path syntax is a subset of JSON Pointer, using forward slashes and zero-based array indices. Escaping rules cover special characters like the tilde and forward slash. For an API serving Australian clients, sticking to the standard avoids subtle bugs when timestamps formatted in AEST are accidentally corrupted by a misencoded path segment.

Preparing the Spring Boot project

Start by creating a new Spring Boot project using your preferred build tool. The only extra dependency you need beyond the standard spring-boot-starter-web is the json-patch library, which can be pulled in via Maven or Gradle. Recent Spring Boot versions also play nicely with jakarta.json, so you may want to include its API artefact to keep the type system consistent with the rest of your stack.

Maven dependencies to include

The versions can be left to Spring Boot's dependency management when possible. If you are running on a private artefact repository hosted in a Sydney data centre, confirm that the json-patch library is mirrored locally to avoid slow first-time builds.

Designing the patch endpoint

A common pattern is to expose PATCH on a versioned resource path such as /api/v1/customers/{id}. The method accepts a JSON Patch document in the body, typically as application/json-patch+json, and returns the updated resource. Using this media type rather than the generic application/json makes the intent explicit and lets intermediaries cache or route the request correctly.

Inside the controller, the typical flow is to fetch the current entity, hand it to the service layer together with the patch document, persist the result, and return it. Make sure to use a typed request body rather than a raw string so that malformed payloads fail early with a 400 response.

Applying the patch in the service layer

The service is where most of the logic lives. Convert the entity to a JsonNode, build a JsonPatch from the incoming array of operations, apply it, and convert the result back to your entity type. For example, a replace operation on /email would update only that field while leaving everything else untouched, which is ideal for compliance workflows where every change must be auditable under the Privacy Act and the Notifiable Data Breaches scheme.

Concurrent updates are worth handling explicitly. A test operation on an /updatedAt or /version field can act as a lightweight optimistic lock. If the test fails, return a 409 Conflict instead of silently overwriting newer data. In a Melbourne-based trading platform, this kind of guard prevents stale quotes from clobbering fresh ones during market open.

Validation, error handling and testing

Patch documents can be malformed in subtle ways. Validate that the path actually points somewhere in your schema, that operations do not remove required fields, and that the result remains serialisable. A custom exception handler returning RFC 7807 problem details keeps the error format consistent with the rest of your API.

Scenarios worth covering in tests

Integration tests with MockMvc or WebTestClient can round-trip real JSON payloads and confirm that the response body matches the entity after patching. In CI pipelines hosted in the APAC region, running these tests against an ephemeral database keeps the feedback loop tight without affecting staging environments in Brisbane or Sydney.

Production checklist before going live

Before exposing the endpoint to customers, walk through a short readiness review. Confirm that the JSON Patch media type is documented in your OpenAPI specification, that audit logs capture the full patch document with AEST timestamps, and that rate limits apply per consumer.

For organisations subject to APRA CPS 234, ensure patch operations are logged with enough detail to reconstruct any change to a customer record. A second pass should verify that your monitoring alerts fire when a patch request returns 422 or 409, as both usually indicate a client bug worth chasing down quickly. Australian engineering teams often automate these checks as part of a release pipeline so the review does not become a manual bottleneck.