Building a JSON Patch endpoint in ASP.NET Core Web API

Modern backend teams across Sydney, Melbourne, and Brisbane routinely deal with client applications that need to mutate a subset of fields on a server-side resource without replacing it entirely. Full PUT requests force clients to send the entire object, which wastes bandwidth and risks unintended overwrites. A well-implemented JSON Patch endpoint solves both problems while keeping the contract RESTful and aligned with what mobile clients actually send.

The JSON Patch specification, formally RFC 6902, defines a series of operations such as add, remove, replace, move, copy, and test that can be applied to a target JSON document. ASP.NET Core ships with first-class support for this standard through Microsoft.AspNetCore.JsonPatch and Microsoft.AspNetCore.Mvc.NewtonsoftJson, making it straightforward for Australian development shops to expose efficient partial-update endpoints in their public and internal APIs.

JSON Patch fundamentals and the RFC 6902 specification

Before writing any code, it helps to understand exactly what RFC 6902 promises. Each patch document is a JSON array of operation objects. Every operation carries an op member naming the action, a path member locating the target using a JSON Pointer (RFC 6901), and an optional value member holding the new data. For example, {"op":"replace","path":"/email","value":"new@example.com"} instructs the server to swap the email field in one atomic call.

The specification also defines evaluation order, atomicity, and error semantics. A patch document must be processed as a single transaction: if one operation fails, the whole request is rejected. This behaviour pairs nicely with the strict expectations of Australian regulators around data integrity, particularly in finance and healthcare where partial application of a change could create an inconsistent record in the source of truth.

Because the operations target specific paths, a misbehaving client cannot stomp on fields it has no business touching, as long as the server enforces a strict allow-list of addresses. That guarantee matters when an API is consumed by mobile apps in regions with patchy 4G coverage along the Nullarbor Plain, where every kilobyte saved on the wire translates to a smoother user experience and lower data costs.

Project setup and required NuGet packages

To follow this walkthrough, you should have the .NET 8 SDK installed locally, alongside an IDE of your choice such as Visual Studio 2022, JetBrains Rider, or VS Code with the C# Dev Kit extension. From a terminal in the project directory, scaffold a new Web API and pull in the patch libraries in a single pass.

dotnet new webapi -n CustomerService
cd CustomerService
dotnet add package Microsoft.AspNetCore.JsonPatch

If your project already uses Newtonsoft.Json rather than System.Text.Json, also add Microsoft.AspNetCore.Mvc.NewtonsoftJson and register the formatter in Program.cs with AddNewtonsoftJson(). For teams in Adelaide or Perth running greenfield services, the default System.Text.Json pipeline is usually sufficient and avoids the extra dependency.

You will also need a persistence layer. For brevity this guide uses EF Core with SQLite, but the patch logic itself is independent of the database. Many Australian consultancies standardise on SQL Server for enterprise work and PostgreSQL for startups; both work transparently here, and the choice rarely changes more than a connection string.

Crafting the Patch endpoint with JsonPatchDocument

Create a simple domain entity, a database context, and a controller exposing a PATCH method. The controller signature is what makes the integration feel idiomatic in ASP.NET Core, and the code stays short because the framework does the heavy lifting of walking the operations and applying them to the model.

[HttpPatch("{id:int}")]
public async Task<IActionResult> PatchCustomer(int id,
    [FromBody] JsonPatchDocument<Customer> patchDoc,
    CancellationToken ct)
{
    var customer = await _db.Customers.FindAsync(new object[] { id }, ct);
    if (customer is null) return NotFound();

    patchDoc.ApplyTo(customer, ModelState);

    if (!ModelState.IsValid) return ValidationProblem(ModelState);

    await _db.SaveChangesAsync(ct);
    return NoContent();
}

Three details deserve attention. First, ApplyTo mutates the entity directly, so any field-level invariants on Customer should be enforced inside the model rather than relying on the database alone. Second, calling ModelState.AddModelError from inside an OperationFilter lets you reject invalid patches with rich diagnostic output. Third, returning NoContent() aligns with the REST convention that a successful partial update carries no representation body.

For teams operating under the Australian Privacy Principles, this last point is worth noting: the API never echoes sensitive fields back to the caller, reducing the surface area for accidental PII disclosure in logs and proxies that route through Canberra-based government gateways.

Validation, error handling, and observability

Validation in a JSON Patch endpoint has two layers: structural validation of the patch document itself, and business-rule validation of the resulting entity. The built-in [FromBody] model binder catches malformed JSON and reports a 400 with details. To restrict the set of operations a client may invoke, inject an IObjectModelValidator or write a custom action filter that walks the patch document before ApplyTo runs and rejects anything outside an allow-list of paths.

Error responses should follow the RFC 7807 Problem Details shape that ASP.NET Core already serialises when you return ValidationProblem. Include the failed operation index and the offending path in the errors dictionary so mobile clients in regional Queensland or Tasmania can show users exactly what went wrong without a round of guesswork.

Observability ties into tracing. Once a patch endpoint is live, you will want to see how long each PATCH takes, which paths are most frequently targeted, and how often validation fails. OpenTelemetry provides that visibility. If you want a practical walkthrough of wiring it up in .NET, this distributed tracing walkthrough covers exactly the patterns you would apply here. Pair the trace data with structured Serilog or ILogger output, and you have a complete picture of every mutating request hitting your service from Sydney CBD to the Pilbara.

Testing and documenting the JSON Patch endpoint

The final piece is verification. Use WebApplicationFactory together with the in-memory provider to spin up the API inside an xUnit or NUnit project, then submit patch documents directly with HttpClient. Cover the happy path, an attempt to add an invalid path, a test operation that fails, and an atomicity check that confirms a mid-document failure leaves the resource untouched.

Swagger ships a slightly bare-bones representation of JSON Patch, so consider installing Swashbuckle.AspNetCore.JsonPatch or writing a small custom filter to expose the operation shapes in the OpenAPI document. Many Australian teams publish their API contracts to a central portal; richer schemas reduce back-and-forth between frontend and backend during sprint planning, which matters when product managers split their week between Melbourne and remote work from a coastal town.

Operational checklist for production rollouts

• Reject patches targeting properties outside an explicit allow-list and return a clear error.
• Wrap ApplyTo and SaveChangesAsync in a single transaction so failures roll back consistently with the atomicity guarantee of RFC 6902.
• Log the patch document, the resulting state, and a correlation id, but redact PII before it leaves the process boundary.
• Publish the supported operations in your OpenAPI document so client teams in Melbourne and across the country know exactly what they can send.
• Rate-limit PATCH endpoints separately from GETs because they trigger database writes and downstream notifications.
• Pin the JsonPatch NuGet package to a known-good version and review CVE advisories on each upgrade.
• Add an integration test that submits a deliberately broken operation followed by a valid one and asserts that no state changes occurred.