HTTP 204 Is the Best DELETE Response
Sometimes, an empty response is the best response.
"The best response for an HTTP DELETE operation is not an HTTP 200 status code with whatever response body you come up with." That's how I started a post I published on social media a few days ago. What I thought was that the post would get a few likes and, at best, a couple of comments. What I didn't anticipate was that the post would grow to a couple of hundred reactions (likes included) and almost one hundred comments. One hundred comments from dozens of people sharing their opinions about the best response for an HTTP DELETE operation. Did they all agree with me? Keep reading to find out.
This article is brought to you with the help of our supporter, DreamFactory:
DreamFactory is the easiest way to automatically generate, publish, manage, and secure REST APIs, convert SOAP to REST, and aggregate disparate data sources through a single API platform.
The first few comments I received were all positive. Everyone seemed to agree that the best response for an HTTP DELETE would be a 204 code with an empty body. Some of those early comments even highlighted the advantages a 204 has over other responses. Other comments opened threads between participants about other HTTP methods and their responses. Overall, there was a multitude of opinions being shared as comments on that post of mine. I couldn't remotely imagine I would open such a Pandora's box. Not in a bad way, I mean. I enjoyed reading every single one of those comments and even learned from some of them.
One comment that caught my attention asked why I advocated for an empty body. Its author couldn't understand why I didn't favor a response that included information about the status of the delete operation. Or, why I didn't bother to include the number of successfully deleted items in the response. My opinion is simple. The status of the delete operation is successful if the response is empty and the HTTP status code is 204. Otherwise, the response will include an HTTP error, and its body will include the corresponding details. About the number of deleted items, I see the HTTP DELETE as an operation that affects one single item, not many. Therefore, there's no need to think about responding with information about the number of deleted items.
A few other comments insisted on responding with an HTTP 200 with a body that includes information about the deleted item. The authors of those comments stated that some consumers could see value in using information about the deleted item after the fact. The way I see it, if consumers really need the information about the deleted item, they can obtain it by making an HTTP GET request to read the item before deleting it. They could even show the information to an end user and ask for confirmation before attempting a delete operation. Then, receiving an HTTP 204 is a sign that the delete operation was successful, and there's no need to receive any other information. And, I'm not the only one who thinks that way.
Some of the people who agreed with my opinion took their time to share why an HTTP 204 is the best option. Some comments mentioned MDN, in particular their explanation of the HTTP 204 status code. According to MDN, and generally speaking, a 204 "indicates that a request has succeeded, but the client doesn't need to navigate away from its current page." MDN refers to "current page" in the context of frontend development. If you're dealing with a backend implementation it means that the client doesn't need to load more information. MDN goes further and explains that, in response to an HTTP DELETE, it means that the "action was successful, and no further information needs to be supplied." I really like the way MDN explains that the detail is in the fact that API consumers don't need further information. On their HTTP DELETE documentation, they reiterate that. There, they recommend a 204 as the first response to a DELETE operation.
Another source of wisdom that other people referred to is RFC 9110 ("HTTP Semantics") from June 2022. This document obsoletes RFC 7231, which was the one generally referred to when discussing HTTP semantics. So, looking at the RFC 9110 section 9.3.5 about the DELETE method, I can immediately notice the types of responses it recommends. Here, the 204 response isn't the first suggestion but it's still recommended before an HTTP 200 response. To summarize, they first recommend responding with a 202 if the action will "likely succeed" but hasn't yet been enacted. Then they recommend a 204 if the action has been enacted and "no further information is to be supplied." Finally, they recommend the 200 only if you need to respond with "a representation describing the status." Again, here, there's a clear preference for not sharing further information after a successful DELETE operation.
So, why do I think that not returning any information is the best approach? One reason has to do with the nature of the information you'd return after a successful DELETE. Would you return an ID of the deleted resource, a timestamp of the operation, or something else? My perspective is that the API consumer already knows the ID of the deleted resource because it's part of the request URI. And, the timestamp is returned on the Date response header. So, there's no need to add that same information to the response body. The only situation where I'd see value in a response body is when you're attempting to delete multiple resources at once. Then, it could be interesting to receive a list of the IDs of the deleted resources.
To conclude, I'm not saying that an HTTP 204 with an empty body is the only response to a DELETE operation. What I'm saying is that it's the best one. Your situation might, obviously, require a different type of response. In any case, I found that having this debate was positive as I learned a lot from the comments and opened up to new ideas. Oh, and before I forget, here's the original LinkedIn post where all the discussion happened, kindly preserved by the Wayback Machine.