What is the scope of the idempotence requirement on PUT operations within REST?

Question

Let's imagine I have an object that serializes into JSON like so:

{ "Name" : "Mike",
  "Status" : "Too cool for school",
  "Looks" : "Devilishly good"}

Now, imagine I have a http://absoluteTruth.foo/{id} (PUT) URI that edits this object. If I call it with a message body that contains:

{"Name" : "Michael"}

what are the demands of idempotence in the face of requests that (improbably) try to alter the other two values? On one hand, I can see that the PUT request above should result in an object that serializes thusly:

{ "Name" : "Michael",
  "Status" : null,
  "Looks" : null}

That way, no matter what anybody else does, my PUT operation always results in the same output. This, unfortunately, places the requirement on the end user that they do a GET, alter the received data, and send back. (Rich Hickey might admonish you for complecting the updates of your various fields.) On the other hand, I can see that it could result in:

{ "Name" : "Michael",
  "Status" : "Too cool for school",
  "Looks" : "Devilishly good"}

Since we can say that changes to the values of "Status" and "Looks" are not among the side effects of PUT when it is called with only the "Name" parameter specified. However, what is returned from subsequent calls to http://absolutetruth.foo/{id} (PUT) might change from time to time if, for example, someone else stops by to rate Michael nee' Mike's looks even more highly.

While this is not, I suspect, an earth-shattering question, the various RFCs I've read, including 2616, are unclear on the point. I lean toward thinking that PUTting with {"Name" : "Michael"} is idempotent enough if it leaves all other values alone, rather than flattening them. Anyone have a definitive answer with an authoritative source?

Answer 1

HTTP 1.1 specifies that:

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.

This means that the body you send should be considered as a whole representation of the resource. PUT idempotence is a consequence of that.

If you PUT {"Name" : "Michael"} on /bar then your resource will not mention the other "fields" anymore.

If you want to change specifically one attribute, you'll have to define other resources, such as /bar/name.