JSON Merge Patch in ASP.NET Core
Tags: aspnetcore, csharp
Published: 2019-02-04 15:04:47

---
title: JSON Merge Patch in ASP.NET Core
published: true
description: JSON Merge Patch is a way how to perform partial resource updates in REST endpoints
tags: asp.net core, csharp
---
REST is well-known and commonly used pattern for creating web APIs. There are many HTTP verbs, but the most frequently used for building REST services are:
- POST - create new item
- GET - read item
- PUT - update/replace item
- DELETE - delete item

These methods are usually enough for a client to make all operations with a resource. But what if the client wants to change only particular properties of a resource? 
For demonstration scenario lets say we have following object and we want to change the weapon property to "Knife"
```
{
    name: "James Bond"
    age: "45"
    weapon: "Gun"
}
```

Client code in pseudo-C#:
```
srcJson = GET {resourceUrl}
model = Json.Parse<UserModel>(srcJson)
model.weapon = "Knife"
dstJson = Json.Serialize(model)
PUT {resourceUrl}
```
That is the obvious solution - GET the resource, modify it and PUT it back to a server. Depending on your architecture and used languages this might have some drawbacks.
Imagine what happens when your UserModel is missing some properties. They will get lost and not send to the server in a PUT call. In case of default ASP.NET Core/C# setup they will be interpreted as a change to default values leading to a data loss.

# JSON Patch 
PUT call replaces whole object rather then performing partial resource update only. [JSON Patch](https://en.wikipedia.org/wiki/JSON_Patch) was created to modify the resource exactly as you want by sending list of operations rather then the object itself.

JSON PATCH request
```
[
 { op: "replace", path: "/weapon", value: "Knife" }
]
```

Implementation of JSON Patch is part of ASP.NET Core,
This structure allows full control of all properties of a resource including arrays, but also tends to be quite chatty and not very human writeable/readable. 

# JSON Merge Patch
If you are looking for something simpler then JSON Patch, there is other way.
[JSON Merge Patch](https://tools.ietf.org/html/rfc7396) allows you to send changes in the form of original model. There is not a list of operations, but rather a patch object containing only changes that are merged with original resource on the server

JSON Merge patch
```
{
    weapon: "Knife"
}
```
And the result will be
```
{
    name: "James Bond"
    age: "45"
    weapon: "Knife"
}
```


JSON Merge patch is limited compared to full JSON Patch. You cannot remove a property (as missing property means "no change" rather then "remove") and also array operations are limited. 


# Morcatko.AspNetCore.JsonMergePatch
Using JSON Merge Patch in C# is not easy. C# is statically typed language and JSON Merge Patch format expects the exact opposite - it defines the operations by property (non)existence.
[Morcatko.AspNetCore.JsonMergePatch](https://www.nuget.org/packages/Morcatko.AspNetCore.JsonMergePatch) is my implementation of JSON Merge Patch for ASP.NET Core. It is designed to fit nicely into ASP.NET Core architecture. Its API is same as API of full JSON patch. All you have to do to use it is to initialize it in your startup class and make an endpoint that accepts patch object. 


```
// Startup.ConfigureServices
services
    .AddMvc()
    .AddJsonMergePatch();

// Controller
[HttpPatch]
[Consumes(JsonMergePatchDocument.ContentType)]
public void Patch(JsonMergePatchDocument<UserModel> patch)
{
    ...
    patch.ApplyTo(backendModel);
    ...
}
```

That is it.
Notice the `Consumes` attribute. You can use it together with full JSON Patch. Requests ContentType is a way how to distinquish betweens both versions.


In case you are using swagger to generate API documentation for your service you will need to add a `DocumentFilter` to your swagger configuration - see github for more details


{% github Morcatko/Morcatko.AspNetCore.JsonMergePatch %}