Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

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

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)
like image 564
David Avatar asked Dec 04 '13 18:12

David


People also ask

Should a RESTful POST operation return something?

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.

What should you return after successfully creating a new resource with POST?

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.

What is difference between put and POST method in REST API?

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.

Can we use Put instead of POST in rest?

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.


1 Answers

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

like image 72
Robert Harvey Avatar answered Oct 12 '22 07:10

Robert Harvey