In order to respect the best practices of the REST principles, is it best to return the created/updated entity upon a POST/PUT ? Or return an empty HTTP body with the Location header?
More precisely, when a resource is created by a POST, should we return:
- Status 201 + Location header + (the created entity in the HTTP body)
OR
- Status 201 + Location header + (empty body)
When a resource is updated by a PUT, should we return:
- Status 200 + (the updated entity in the HTTP body)
OR
- Status 204 (empty body)
Ideally it would return a success/fail response. Show activity on this post. 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.
According to the specification a POST request is a request to process the payload according to the servers semantics. It is therefore up to the server whether it will create one or not. If it does create a resource representation, however, it should return the URI of the created resource as location header.
Another important difference between the methods is that PUT is an idempotent method, while POST isn't. For instance, calling the PUT method multiple times will either create or update the same resource. In contrast, multiple POST requests will lead to the creation of the same resource multiple times.
If you want to use POST, then you would do that to a list of questions. If you want to use PUT, then you would do that to a particular question. Great, both can be used, so which one should I use in my RESTful design: You do not need to support both PUT and POST.
It might be beneficial to study the API's of other folks to see how they do it. Most of the useful public API's are published somewhere on the web.
For example, the Overmind project publishes their REST API here. In general, their approach is to return a JSON Dictionary containing the new or modified entity ID and all of its attributes:
Operation HTTP Method URL Query string
-------------------------- ----------- --- ------------
Create node for a specific
provider POST /api/nodes/ provider_id=PROVIDER_ID
HTTP Payload returned
---------------------
JSON dict with id of node created (generated on the server side) and all other
attributes of the node
Twilio's API is capable of returning XML or JSON. Twilio returns exceptions in the HTTP response body when something goes wrong. In XML, these appear as a <RestException>
element within the <TwilioResponse>
In general, I can see returning the object on a PUT or POST as useful, because it will contain any modifications made to the properties of the object (such as default values).
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With