RESTful API: Delete Entity - What should I return as result?

Question

I am implementing a RESTful API and an endpoint of one controller is Delete. Delete does two actions depending of the entity to be removed: it updates the entity or it deletes the entity from the database. If delete updates the entity I would send the HttpStatus 200 and the updated entity. But if the delete removes the entity from the database I would send only the HttpStatus 200 . In one case I am returning an object. But in the other case, the object doesn't existe any more. Is it a good approach or I am missing anything?

Answer 1

The commonly considered HTTP Statuses for DELETE include:

• 200 OK (MDN)
• 202 Accepted (MDN)
• 204 No Content (MDN)

204 is ideal if your service is not returning any additional info. It is also popular for PUT update requests. Many services return 204 including Docker as shown below:

• Ref: https://docs.docker.com/engine/api/v1.24/

However, if you are implementing HATEOAS, it is better to use 200 OK and provide some links for the service. Think of an application that has just issued a delete and needs to navigate a user to a location. Without providing a URL for that location, the client app needs to keep state. Providing a 200 OK with a link allows the REST API to keep state for the client.

The following article describes this issue well (read the blog for more discussion):

Avoid 204 responses if you're building a HATEOAS application.

This is a lesson about REST API design that I learned while building non-trivial REST APIs. In order to be as supportive of the client as possible, a REST API should not return 204 (No Content) responses.

From the service's perspective, a 204 (No Content) response may be a perfectly valid response to a POST, PUT or DELETE request. Particularly, for a DELETE request it seems very appropriate, because what else can you say?

However, from the perspective of a proper HATEOAS-aware client, a 204 response is problematic because there are no links to follow. When hypermedia acts as the engine of application state, when there are no links, there's no state. In other words, a 204 response throws away all application state.

If a client encounters a 204 response, it can either give up, go to the entry point of the API, or go back to the previous resource it visited. Neither option is particularly good.

• Ref: http://blog.ploeh.dk/2013/04/30/rest-lesson-learned-avoid-204-responses/

Answer 2

Short answer

The suitable status codes for a DELETE request that has succeeded are 200 , 202 and 204 .

Long answer

DELETE does two actions depending of the entity to be removed: it updates the entity or it deletes the entity from the database. [...] Is it a good approach or I am missing anything?

The DELETE method is not meant for performing updates.

See the following quote from the RFC 7231 , one of the documents the define the HTTP/1.1 protocol, for details on what the DELETE method is about:

4.3.5. DELETE

The DELETE method requests that the origin server remove the association between the target resource and its current functionality. In effect, this method is similar to the rm command in UNIX: it expresses a deletion operation on the URI mapping of the origin server rather than an expectation that the previously associated information be deleted. [...]

If the delete operation has succeded , the server can return one of the following status codes:

• 202 : Indicates that the request has been accepted for processing, but the processing has not been completed.
• 204 : Indicates that the server has successfully fulfilled the request and that there is no additional content to send in the response payload body.
• 200 : Indicates that the request has succeeded and the request payload includes a representation of the status of the action.

See the following quote from the same document:

If a DELETE method is successfully applied, the origin server SHOULD send a 202 (Accepted) status code if the action will likely succeed but has not yet been enacted, a 204 (No Content) status code if the action has been enacted and no further information is to be supplied, or a 200 (OK) status code if the action has been enacted and the response message includes a representation describing the status.