Partial Entity Updates in WebAPI PUT/POST

Question

Say you have a repository method to update a Document:

public Document UpdateDocument(Document document)
  {
  Document serverDocument = _db.Documents.Find(document.Id);
  serverDocument.Title = document.Title;
  serverDocument.Content = document.Content;
  _db.SaveChanges();
  return serverDocument;
  }

In this case, the entity has two properties. When updating a Document, both of these properties are required in the JSON request, so a request to PUT /api/folder with a body of

{
  "documentId" = "1",
  "title" = "Updated Title"
}

would return an error because "content" was not provided. The reason I'm doing this is because, even for nullable properties and properties that the user doesn't update, it seems safer to force the client to specify these fields in the request to avoid overwriting unspecified fields with nulls serverside.

This has led me to the practice of always requiring every updatable property in PUT and POST requests, even if it means specifying null for those properties.

Is this cool, or is there a pattern/practice that I haven't learned about yet that might facilitate partial updates by sending only what is needed over the wire?

Answer 1

The best practice in API design is to use HTTP PATCH for partial updates. In fact, use cases like yours are the very reason why IETF introduced it in the first place.

RFC 5789 defines it very precisely:

PATCH is used to apply partial modifications to a resource.

A new method is necessary to improve interoperability and prevent
errors. The PUT method is already defined to overwrite a resource
with a complete new body, and cannot be reused to do partial changes. Otherwise, proxies and caches, and even clients and servers, may get
confused as to the result of the operation. POST is already used but without broad interoperability (for one, there is no standard way to
discover patch format support).

Mark Nottingham has written a great article about the use of PATCH in API design - http://www.mnot.net/blog/2012/09/05/patch

In your case, that would be:

  [AcceptVerbs("PATCH")]
  public Document PatchDocument(Document document)
  {
      Document serverDocument = _db.Documents.Find(document.Id);
      serverDocument.Title = document.Title;
      serverDocument.Content = document.Content;
      _db.SaveChanges();
      return serverDocument;
  }