How should I update a REST resource?

Question

I'm not sure how I should go about updating individual properties of a REST resource. Consider the following example:

# HTTP GET to /users/1.xml
<?xml version="1.0" encoding="UTF-8" ?>
<response>
   <user>
      <id>1</id>
      <name>John Doe</name>
      <email>[email protected]</email>
   </user>
</response>

How should I facilitate for updating John's email? HTTP PUT comes to mind, but I'd be making it hard on my clients by requiring a complete XML (matching the HTTP GET response) to modify the resource.

The PUT method requests that the enclosed entity be stored under the supplied Request-URI. If the Request-URI refers to an already existing resource, the enclosed entity SHOULD be considered as a modified version of the one residing on the origin server.

Is there any other way?

Answer 1

If your server framework is flexible enough to handle it, you can do:

Request:
PUT /users/1/email
Content-Type: text/plain

[email protected]

Response:
200 OK
Content-Location: /users/1

By using a URL to refer to the email as its own resource, you can PUT directly to it using a simple format like text/plain. In the response, the Content-Location url gives the client an indication that the change has had an impact on the user resource.

The PATCH method is also another way that you can do partial updates. This is a newly introduced method and as yet there are no standard formats for sending XML diff documents. So, if you take this approach you will not find much guidance.

The other thing to consider is that REST works best with large grained updates. If you find yourself needing to make these kinds of small changes, then maybe you need to rethink your distributed architecture.