rest - What's the currently recommended way of performing partial updates with Web API?

Question

I'm wondering how to implement partial updates with ASP.NET Web API's RESTful interface? Let's say for example we are passing objects over the wire of the following structure:

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

How would one support updating just parts of a Person at a time, for example the Email property? Is it recommended to implement this via OData and the PATCH verb, or would it be better to implement PATCH oneself?

Answer 1

There is no support in the current latest stable release of Web API (from August 2012). So if all you want to use is Web API RTM, you would have to implement the whole plumbing yourself.

With that said, OData prerelease package supports partial updates very nicely through the new Delta<T> object. Currently the Microsoft.AspNet.WebApi.OData package is at RC version already (0.3) and can be obtained from here: http://www.nuget.org/packages/Microsoft.AspNet.WebApi.OData

Once you install that, you can then use that accordingly:

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

And you'd call it from the client like this:

$.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 don't have to care whether you update Email or Username or whatnot.

You might also want to look into this post, as it shows a very similar technique http://techbrij.com/http-patch-request-asp-net-webapi

EDIT (more info): In order to just use PATCH, you do not need to enable anything OData related, except for adding the OData package - to get access to the Delta<TEntityType> object.

You can then do this:

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 is, let's say:

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

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

{
    "Name": "changed!"
}

and that will correctly update your object.

Delta<TEntity> will keep track of the changes for you. It is a dynamic class that acts as a lightweight proxy for your Type and will understand the differences between the original object (i.e. from the DB) and the one passed 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 facilitate the OData package dependencies).

I have added a sample project to demonstrate the work of PATCH + Delta - you can grab it here (it.s VS2012) https://www.dropbox.com/s/hq7wt3a2w84egbh/MvcApplication3.zip