REST Best Practices: Should you return an entity on POST and PUT calls?

Question

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)

I guess you're talking about a REST API, not just e.g. an app working the REST way? — pdu, Dec 04 '13 at 18:29
@pduersteler: yes, I am talking about a REST Json API (no html). — David, Dec 04 '13 at 18:42

Robert Harvey · Accepted Answer · 2013-12-04T19:08:31.073

21

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).

edited Dec 04 '13 at 19:08

answered Dec 04 '13 at 18:41

Robert Harvey

178,213
47
333
501

3

So far, I've looked at Amazon s3 API which does not seem to return the entities in the response body (http://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPOST.html). But Google Apps API does return them (https://developers.google.com/google-apps/calendar/v3/reference/). I think too that it makes sense to return the entities in the response, except I am not an expert with HTTP proxies so I'm not sure what is the impact of including the entity on caching or other features of HTTP proxies. – David Dec 08 '13 at 18:11
As it does not seemed to exists a definitive standard, I am marking your answer as accepted for the effort. – David Dec 09 '13 at 20:43
5

Honestly, this is the most appropriate answer (and people who insist a RESTful POST/PUT should not contain an entity in its response are doing religion, not engineering.) – luis.espinal Oct 09 '19 at 19:31

REST Best Practices: Should you return an entity on POST and PUT calls?

1 Answers1

Linked