If I have a REST server and do PUT on an resource, should the server return new resource state in the response, or should the response body be empty?
RFC-7231 is suspiciously silent about that. It has a lengthy discussion on what status code to return, but says virtually nothing about the response body. It is clear that empty response body is legal, since one of possible return codes is 204 No Content, but there is no recommendation about non-empty bodies.
One can make arguments for both empty and non-empty body. PUT is allegedly supposed to create or replace the resource in its entirety (although RFC does not explicitly say that), so the client should know what resultant state it seeks. Thus, sending back full fledged resource state will only waste the bandwidth.
From the other hand, the RFC states that the server is allowed to modify client input to make it conform to the internal rules, e.g. convert the input to a different format. Additionally, the resource may contain calculated fields that are hard or impossible to obtain on the client: modification time, number of hits, current orbital momentum, link to the XKCD cartoon the server deems the most relevant to the subject, etc. In most of those scenarios the client will have to issue an immediate GET request to fetch the data back from the server, so why not just serve it back right away and save a round-trip?
Presence of calculated fields raises other interesting subjects. E.g. if the client makes the same PUT request twice and gets different calculated fields back, does it mean the PUT implementation is not idempotent? If the client sends wrong values of the calculated fields in, should PUT request be rejected by the server? But I digress.
If you search the Internet, you will find equally convincing opinions (with lots of upvotes) that the body should be empty, because it’s THE RIGHT WAY, and that the body should not be empty, because it makes client’s life unnecessarily hard.
After giving it some thought, I think the server SHOULD return new resource state when practical. I initially wrote a server that returns an empty body, and immediately found myself doing GET in the client immediately following any successful PUT. This does not feel right. Of course, there are cases when the state is too large to return (think of PUTting a 100MB file), but I feel these are the exception rather than the norm.
PS. I suspect the RFC says nothing about the response body, because the committee members could not agree on what recommendation to PUT in 🙂
Links:
http://tools.ietf.org/html/rfc7231#section-4.3
http://blog.ploeh.dk/2013/04/30/rest-lesson-learned-avoid-204-responses/
http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
http://stackoverflow.com/questions/797834/should-a-restful-put-operation-return-something
http://stackoverflow.com/questions/29217881/in-rest-if-updating-an-object-automatically-changes-the-last-modified-date-s
http://stackoverflow.com/questions/9450611/put-and-idempotent
http://51elliot.blogspot.com/2014/05/rest-api-best-practices-3-partial.html
http://programmers.stackexchange.com/questions/211275/should-an-http-api-always-return-a-body