What is the currently recommended way to partially update the web API?

Question

I am wondering how to implement partial updates using the ASP.NET Web API RESTful? Say, for example, we pass objects through a wire of the following structure:

public class Person { public int Id { get; set; } public string Username { get; set; } public string Email { get; set; } } 

How can I support updating only parts of Person at a time, for example, the Email property? Is it recommended to implement this using OData and the verb PATCH, or would it be better to implement PATCH yourself?

Answer 1

There is no support in the current latest stable version of the Web API (since August 2012). Therefore, if all you want to use is RTM for the web API, you will have to implement all the plumbing yourself.

With this in mind, the OData preerelease package supports partial updates very well with the new Delta<T> object. Currently, the Microsoft.AspNet.WebApi.OData package is already in RC (0.3) and can be obtained here: http://www.nuget.org/packages/Microsoft.AspNet.WebApi.OData

Once you install this, you can use it accordingly:

 [AcceptVerbs("PATCH")] public void Patch(int id, Delta<Person> person) { var personFromDb = _personRepository.Get(id); person.Patch(personFromDb); _personRepository.Save(); } 

And you would call it from the client as follows:

 $.ajax({ url: 'api/person/1', type: 'PATCH', data: JSON.stringify(obj), dataType: 'json', contentType: 'application/json', success: function(callback) { //handle errors, do stuff yada yada yada } }); 

The obvious advantage of this is that it works for any property, and you do not need to worry about whether you are updating Email or Username or something else.

You can also watch this post as it shows a very similar technique http://techbrij.com/http-patch-request-asp-net-webapi

EDIT (more): To simply use PATCH, you do not need to include anything related to OData, except to add the OData package - to access the Delta<TEntityType> object.

Then you can do the following:

 public class ValuesController : ApiController { private static List<Item> items = new List<Item> {new Item {Id = 1, Age = 1, Name = "Abc"}, new Item {Id = 2, Age = 10, Name = "Def"}, new Item {Id = 3, Age = 100, Name = "Ghj"}}; public Item Get(int id) { return items.Find(i => i.Id == id); } [AcceptVerbs("PATCH")] public void Patch(int id, Delta<Item> item) { var itemDb = items.Find(i => i.Id == id); item.Patch(itemDb); } } 

If your item, say:

 { "Id": 3, "Name": "hello", "Age": 100 } 

You can PATCH on /api/values/3 with:

 { "Name": "changed!" } 

and this will update your object correctly.

Delta<TEntity> will track the changes for you. This is a dynamic class that acts as an easy proxy for your Type and will understand the differences between the original object (i.e. From the database) and the one that was sent by the client.

This will NOT affect the rest of your API in any way (except, of course, replacing the DLLs with newer ones to ease the dependencies of the OData package).

I added an example project to demonstrate how PATCH + Delta works - you can capture it here (it.s VS2012) https://www.dropbox.com/s/hq7wt3a2w84egbh/MvcApplication3.zip