In REST, should I return the representation in response to a PUT?

Question

It is conceivable that another client also modified other aspects of the resource in the interim. So is it best practice to always include the full representation in the response to a PUT, despite the bandwidth overhead?

Answer 1

I like to think of GET and DELETE being pairs -- they take only an ID.

POST and POST seem like pairs. They take a serialized object and make it persistent. Consequently, I think both POST and PUT should return the resulting object as created.

In some cases, you may be doing additional calculations as part of the persistence, and the PUT could reflect those calculated results. Technically, this might be a 3rd normal form violation because you have derived values. But often, the whole point of the web service is to do some value-adding calculation as part of POST and possibly PUT.

Answer 2

Jldupont's comment pointed me in the right direction. I will use ETags to determine whether the resource has been modified, by doing a conditional PUT using the If-match header, as described here.

Then, in case of a conflict, I'll let the user decide whether to fetch the latest representation from the server (GET) or overwrite the changes with his own.

Thus, there is no need to return the full representation in the response to the PUT just to help with conflict detection and resolution.

Answer 3

In many (if not most) cases, the server will add something to the resource even if it's created or updated via PUT. Examples are timestamps, a version number, or any element computed from others. This is true even if you follow the RESTful approach and do not use PUT for partial updates.

For this reason alone, returning the updated or created resource's representation is often a good idea for PUT requests. I wouldn't necessarily call it a "best practice", though – if you PUT a giant 2GB image file you probably do not want to return it as part of the response.

Including an ETag, on the other hand, definitely deserves "best practice" status.