Question

Why does an HTTP PUT request have to contain a representation of a ‘whole’ state and can’t just be a partial?

I understand that this is the existing definition of PUT – this question is about the reason(s) why it would be defined that way.

i.e:

What is gained by preventing partial PUTs?

Why was preventing idempotent partial updates considered an acceptable loss?

Answer 1

PUT means what the HTTP spec defines it to mean. Clients and servers cannot change that meaning. If clients or servers use PUT in a way that contradicts its definition, at least the following thing might happen:

Put is by definition idempotent. That means a client (or intermediary!) can repeat a PUT any number of times and be sure that the effect will be the same. Suppose an intermediary receives a PUT request from a client. When it forwards the request to the server, there is a network problem. The intermediary knows by definition that it can retry the PUT until it succeeds. If the server uses PUT in a non idempotent way these potential multiple calls will have an undesired effect.

If you want to do a partial update, use PATCH or use POST on a sub-resource and return 303 See Other to the ‘main’ resource, e.g.

POST /account/445/owner/address
Content-Type: application/x-www-form-urlencoded

street=MyWay&zip=22222&city=Manchaster


303 See Other
Location: /account/445

EDIT: On the general question why partial updates cannot be idempotent:

A partial update cannot be idempotent in general because the idempotency depends on the media type semantics. IOW, you might be able to specify a format that allows for idempotent patches, but PATCH cannot be guaranteed to be idempotent for every case. Since the semantics of a method cannot be a function of the media type (for orthogonality reasons) PATCH needs to be defined as non-idempotent. And PUT (being defined as idempotent) cannot be used for partial updates.