22

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?

Kevin Pauli
  • 8,577
  • 15
  • 49
  • 70
  • would it be better to return a unique identifier associated with the transaction? Saves on bandwidth and avoids potentially having to return to the server anyways to make sure nothing happened in the interim. I.e. if you return the data, it might anyhow be stale. – jldupont Jan 14 '10 at 16:29
  • 1
    That's uncanny... I was asking myself that very same question 20 minutes ago... – skaffman Jan 14 '10 at 16:31

4 Answers4

19

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.

Stefan Tilkov
  • 1,683
  • 12
  • 10
  • I like this answer,as it mentions how returning the resource can be of help, but stays true to the fact that it's not something that's always a good idea either. One thing worth noting is that such response sadly will not be cached, as currently there is no mechanism for making PUT cache the representation from the response. Rfc7231 [describes one for the request](//tools.ietf.org/html/rfc7231#section-4.3.4), but it only works when the server DIDN'T add anything to the resource (see [this comment](//stackoverflow.com/questions/107390#comment114471286_107450)). – Slawomir Brzezinski Nov 08 '20 at 20:36
8

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.

Kevin Pauli
  • 8,577
  • 15
  • 49
  • 70
7

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

POST and PUT seem like a pair as well. 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.

Russ Amos
  • 419
  • 3
  • 9
S.Lott
  • 384,516
  • 81
  • 508
  • 779
  • I appreciate your philosophy, but disagree (at least partially). The HTTP spec does not (as it does for GET) require/forbid/limit DELETE to just a URL. More importantly, you are *not* the only one who thinks this is the case (and much more importantly, major software projects like Talend are designed around this assumption. ) DELETE requests for single entities don't need a body (like GET), but DELETE requests for collections are incredibly drastic without some data that refines the request – Anthony Sep 11 '15 at 11:51
3

You may wish to consider returning a 303 See Other response with the Location header set to the URI of the updated resource (Post/Redirect/Get). This way the client receives the current state of the resource (if it chooses to follow the Location header) even if it has been edited in the interim, and is not in danger of resubmitting the request if using a browser.

However, this pattern precludes sending the appropriate success code (200 OK, 202 Accepted, etc.) which may be useful to the client. Also, depending on your definition of REST, you may consider this to be non-standard practice.

It's probably more appropriate if the clients are likely to be browsers operated by people.

Ian Mackinnon
  • 13,381
  • 13
  • 51
  • 67