If you’re building a RESTful API, you’ll soon come across the scenario where you need to delete some resource, so you make an endpoint with the DELETE verb. Someone calls that endpoint, and you have some options for what to return:
- HTTP 202 – the entity is not deleted but you’ve enqueued the request to delete the item, and the system will get to it.
- HTTP 200 – the entity is deleted and you need to return some entity to the caller (maybe some kind of receipt).
- HTTP 204 – the entity is deleted and there’s nothing to return.
Now onto the final scenario: the entity doesn’t exist. How do you respond? The options are universally argued to be between 204 and 404.
You can get into this situation in a couple of ways:
- The resource never existed.
- Multiple requests to delete the resource were sent, which can be for a variety of reasons, race conditions being the one that can’t reasonably be prevented.
When thinking of the difference between 204 and 404, I try to think of what the response code tells the user:
- 204 says “the call was a success: the system does not contain the item you requested for deletion”
- 404 says “the call was not a success: the system did not contain the item you requested for deletion”
When comparing them like that, a 404 doesn’t make sense. It is my contention that the 404 scenario is, instead, vacuously successful, and should be a 204. Whether the data was deleted in a race with another caller, deleted in a previous call that failed to return a response (prompting the client to retry), or succeeded vacuously because the data wasn’t there to begin with, it doesn’t so much matter. The request to have the resource deleted was successful. Whether or not the server had to do work to actually delete anything is irrelevant, and a 404 probably breaks the abstraction that the endpoint’s contract provides.
Those are my thoughts. Hope it helps.