I used RESTful API in my services, and here is my opinion:
First we must get to a common view: PUT
is used to update an resource not create or get.
I defined resources with: Stateless resource
and Stateful resource
:
Stateless resources For these resources, just return the HttpCode with empty body, it's enough.
Stateful resources For example: the resource's version. For this kind of resources, you must provide the version when you want to change it, so return the full resource or return the version to the client, so the client need't to send a get request after the update action.
But, for a service or system, keep it simple
, clearly
, easy to use and maintain
is the most important thing.
The HTTP/1.1 spec (section 9.6) discusses the appropriate response/error codes. However it doesn't address the response content.
What would you expect ? A simple HTTP response code (200 etc.) seems straightforward and unambiguous to me.
If the backend of the REST API is a SQL relational database, then
If you don't care about lost updates, or if you want to force your clients to do a GET immediately after a PUT, then don't return anything from PUT.
Ideally it would return a success/fail response.
Http response code of 201 for "Created" along with a "Location" header to point to where the client can find the newly created resource.
There's a difference between the header and body of a HTTP response. PUT should never return a body, but must return a response code in the header. Just choose 200 if it was successful, and 4xx if not. There is no such thing as a null return code. Why do you want to do this?
I think it is possible for the server to return content in response to a PUT. If you are using a response envelop format that allows for sideloaded data (such as the format consumed by ember-data), then you can also include other objects that may have been modified via database triggers, etc. (Sideloaded data is explicitly to reduce # of requests, and this seems like a fine place to optimize.)
If I just accept the PUT and have nothing to report back, I use status code 204 with no body. If I have something to report, I use status code 200, and include a body.
seems ok... though I'd think a rudimentary indication of success/failure/time posted/# bytes received/etc. would be preferable.
edit: I was thinking along the lines of data integrity and/or record-keeping; metadata such as an MD5 hash or timestamp for time received may be helpful for large datafiles.
Just as an empty Request body is in keeping with the original purpose of a GET request and empty response body is in keeping with the original purpose of a PUT request.
As opposed to most of the answers here, I actually think that PUT should return the updated resource (in addition to the HTTP code of course).
The reason why you would want to return the resource as a response for PUT operation is because when you send a resource representation to the server, the server can also apply some processing to this resource, so the client would like to know how does this resource look like after the request completed successfully. (otherwise it will have to issue another GET request).
Source: Stackoverflow.com