Note: This article was originally published on 04/05/2021.

These two articles are to discuss JSON Patch.

A: Introduction

In the ASP.NET fields, both MVC and Web API modules, we are fimilar with creating the controller based on the output entity object to get CRUD actions for us, i.e., the Verbs: GET, POST, PUT, and DELETE:

These methods are used to access database.

Actually, there is one more Verb: Patch, available. Then we have the Verbs like this

The Methods and Verbs

Json Patch In ASP.NET Core web API

The patch method is responsible to the patial update. We will discuss this issue in this article. We will discuss in the order below:

B: What is Patch


1, Full Update vs. Patial Update

The Verb PUT update the database the whole record. However, sometimes, the client only want to update one field or partial fields in the records, sometimes, client side even does not have full info to update the records in whole, in this situation, a partial update is a better solution or required, that is what PATCH jumps in.

Therefore, the HTTP Verbs will be like this,

Json Patch In ASP.NET Core web API

2, What is JSON Patch?

JSON Patch is a format for describing changes to a JSON document. It can be used to avoid sending a whole document when only a part has changed. When used in combination with the HTTP PATCH method, it allows partial updates for HTTP APIs in a standards compliant way.

JSON Patch is specified in RFC 6902 from the IETF.

3, How Json Patch works?

A JSON Patch document is just a JSON file containing an array of patch operations. The patch operations supported by JSON Patch are “add”, “remove”, “replace”, “move”, “copy” and “test”. The operations are applied in order: if any of them fail then the whole patch operation should abort.

Json Patch In ASP.NET Core web API

C: Patch Implementation in ASP.NET Core Web API, in Memory

We will demo the PATCH result in ASP.NET Core Web API app with Swagger support.

1, Configure the App

Step 1: Create an ASP.NET Core MVC application

We use the current version of Visual Studio 2019 16.9.3 and .NET 5.0 SDK to Create an ASP.NET Core Web API app, see here for details.

Step 2: Configure app

To enable JSON Patch support, we need to install the Microsoft.AspNetCore.Mvc.NewtonsoftJson from NuGet package

2, Add PATCH related files:

Step 1: Add two entity classes:

Add two classes: Customer and Order:

using System.Collections.Generic;  
  
namespace JsonPatchSample.Models  
{  
    public class Customer  
    {  
        public string CustomerName { get; set; }  
        public List<Order> Orders { get; set; }  
    }  
} 
namespace JsonPatchSample.Models  
{  
    public class Order  
    {  
        public string OrderName { get; set; }  
        public string OrderType { get; set; }  
    }  
} 

Step 2: Add a Controller:

Add a tmpty controller named as: HomeController with following code: 

using JsonPatchSample.Models;    
using Microsoft.AspNetCore.JsonPatch;    
using Microsoft.AspNetCore.Mvc;    
using System.Collections.Generic;    
using System.Dynamic;    
    
namespace JsonPatchSample.Controllers    
{    
    [Route("jsonpatch/[action]")]    
    [ApiController]    
    public class HomeController : ControllerBase    
    {    
        [HttpGet]    
        public IActionResult JsonPatchWithModelState()   
        {    
            var customer = CreateCustomer();    
            return new ObjectResult(customer);    
        }    
   
        [HttpPatch]    
        public IActionResult JsonPatchWithModelState(    
            [FromBody] JsonPatchDocument<Customer> patchDoc)    
        {    
            if (patchDoc != null)    
            {    
                var customer = CreateCustomer();    
    
                patchDoc.ApplyTo(customer, ModelState);    
    
                if (!ModelState.IsValid)    
                {    
                    return BadRequest(ModelState);    
                }    
    
                return new ObjectResult(customer);    
            }    
            else    
            {    
                return BadRequest(ModelState);    
            }    
        }   
  
        private Customer CreateCustomer()  
        {  
            return new Customer  
            {  
                CustomerName = "John",  
                Orders = new List<Order>()  
                {  
                    new Order  
                    {  
                        OrderName = "Order0"  
                    },  
                    new Order  
                    {  
                        OrderName = "Order1"  
                    }  
                }  
            };  
        }  
    }    
}

3, Discussion of Operations:

Run the App:

For the .NET Core 5.0, there is a very good Swagger support for PATCH. If you run a previous version of .NET Core, it might not be the same.

Json Patch In ASP.NET Core web API

Run the App, we have two action methods: GET and PATCH. Run the GET, we will get the Original input data:

Json Patch In ASP.NET Core web API

Run PATCH, we will run the PATCH operations: “add”, “remove”, “replace”, “move”, “copy” and “test”, one by one, all results are against to the original one above:

1. The add operation

The following sample patch document sets the value of CustomerName and adds an Order object to the end of the Orders array.

[  
  {  
    "op": "add",  
    "path": "/customerName",  
    "value": "Barry"  
  },  
  {  
    "op": "add",  
    "path": "/orders/-",  
    "value": {  
      "orderName": "Order2",  
      "orderType": null  
    }  
  }  
]

Shown in app like this,

Json Patch In ASP.NET Core web API

In the preceding JSON:

Then we got the result:

Json Patch In ASP.NET Core web API

The changes made by applying a JSON Patch document to a resource are atomic. If any operation in the list fails, no operation in the list is applied.

2. The remove operation

The following sample patch document sets CustomerName to null and deletes Orders[0]:

JSON

[  
  {  
    "op": "remove",  
    "path": "/customerName"  
  },  
  {  
    "op": "remove",  
    "path": "/orders/0"  
  }  
]

Then we got the result:

Json Patch In ASP.NET Core web API

3. The replace operation

This operation is functionally the same as a remove followed by an add.

The following sample patch document sets the value of CustomerName and replaces Orders[0]with a new Order object:

JSON

[  
  {  
    "op": "replace",  
    "path": "/customerName",  
    "value": "Barry"  
  },  
  {  
    "op": "replace",  
    "path": "/orders/0",  
    "value": {  
      "orderName": "Order2",  
      "orderType": null  
    }  
  }  
] 

Then we got the result:

Json Patch In ASP.NET Core web API

4. The move operation

The following sample patch document:

JSON

[  
  {  
    "op": "move",  
    "from": "/orders/0/orderName",  
    "path": "/customerName"  
  },  
  {  
    "op": "move",  
    "from": "/orders/1",  
    "path": "/orders/0"  
  }  
]

Then we got the result:

Json Patch In ASP.NET Core web API

5. The copy operation

This operation is functionally the same as a move operation without the final remove step.

The following sample patch document:

JSON

[  
  {  
    "op": "copy",  
    "from": "/orders/0/orderName",  
    "path": "/customerName"  
  },  
  {  
    "op": "copy",  
    "from": "/orders/1",  
    "path": "/orders/0"  
  }  
]

Then we got the result:

Json Patch In ASP.NET Core web API

6. The test operation

If the value at the location indicated by path is different from the value provided in value, the request fails. In that case, the whole PATCH request fails even if all other operations in the patch document would otherwise succeed.

The test operation is commonly used to prevent an update when there's a concurrency conflict.

The following sample patch document has no effect if the initial value of CustomerName is "John", because the test fails:

JSON

[  
  {  
    "op": "test",  
    "path": "/customerName",  
    "value": "Nancy"  
  },  
  {  
    "op": "add",  
    "path": "/customerName",  
    "value": "Barry"  
  }  
]

Then we got the result:

Json Patch In ASP.NET Core web API

D: Patch Implementation in ASP.NET Core Web API, for Database

Now we run PATCH for View Models/DTOs from memory, and then we need to apply those patches back onto a database. Years ago, people use Automapper to do the job, and now with .NET Core 5.0 (at least), we can do it just by the Microsoft code. We will demo a short sample here.

It seems even I just introduce the conclusion, this article wil bel still too long, I'd rather leave it to a new article as part II of this one.

Summary

Thia article described the PATCH concept briefly, and discussed the 6 PATCH operations associated with a ASP.NET Core Web API App. We will discuss the PATCH Implementation in ASP.NET Core Web API, for Database, in the next article of part II of this article.

Reference