DELETE: Removing Resources
You'll learn how to use DELETE requests to remove resources from a REST API, what status codes to return, and how to handle resources that no longer exist.
What DELETE Does
The DELETE method removes a resource from the server. Think of it like throwing away a physical file from a filing cabinet — once it's gone, it's gone. DELETE requests target a specific resource identifier (URI) and ask the server to remove that resource entirely.
The 204 No Content Response
When a DELETE succeeds, the most common response is 204 No Content. This status code tells the client "I successfully deleted it, and there's nothing to send back." No response body is needed because the resource no longer exists — there's nothing to describe.
DELETE /api/users/123 HTTP/1.1
HTTP/1.1 204 No Content
Alternatively, some APIs return 200 OK with a confirmation message or the deleted resource's final state, but 204 is cleaner and more semantic.
Handling Already-Deleted Resources
What happens if a client tries to DELETE a resource that's already gone? You have two main options:
- Return 404 Not Found — the resource doesn't exist, so you can't delete it
- Return 204 No Content anyway — the end state is the same (resource is absent), honoring DELETE's idempotent nature
Both approaches are valid. Returning 204 treats DELETE as idempotent: calling it multiple times achieves the same result. Returning 404 is more literal: you can't delete what isn't there.
Idempotency Reminder
Like PUT, DELETE is idempotent. The first DELETE removes the resource. Subsequent DELETEs don't change the server state further — the resource remains absent.
Key Takeaway: DELETE removes resources and typically returns 204 No Content on success; handle already-deleted resources by either returning 204 (idempotent) or 404 (literal).