DELETE
Removing a resource at a known URI requires the HTTP DELETE method, which instructs the server to discard the target resource.
Usage
A DELETE request instructs the server to remove the target resource. The server determines what removal means in practice: the resource might be permanently erased, archived, or marked as inactive.
REST APIs rely heavily on DELETE to represent
resource destruction. An API endpoint like
DELETE /api/users/123 signals a clear intent to remove
the user record identified by 123. This maps directly
to the PUT/POST/GET/DELETE
pattern for create, update, read, and destroy operations.
HTML forms only support GET and POST. JavaScript
APIs such as fetch and XMLHttpRequest support
DELETE natively. Some frameworks use POST with a
_method=DELETE parameter as a workaround.
The server responds with one of several status codes depending on the outcome:
- 200 OK confirms removal and includes a response body describing the result.
- 202 Accepted acknowledges the request but indicates removal has not yet completed.
- 204 No Content confirms removal with no response body.
A hard delete permanently removes the resource. Subsequent GET requests return 404 or 410 Gone. A soft delete marks the resource as inactive without removing the underlying data. The resource remains retrievable through an admin API or with a query parameter. 410 communicates permanent removal, while 404 is appropriate when the resource no longer exists at the URI.
A DELETE request is idempotent. Sending the same request multiple times produces the same server state as sending the request once. The first request removes the resource, and subsequent requests have no additional effect. The response codes might differ, though: the first request returns 200 OK or 204 No Content, while later requests return 404 Not Found or 410 Gone.
Properties
| Property | Value |
|---|---|
| Safe | No |
| Idempotent | Yes |
| Cacheable | No |
Example
Deleting a resource
A client requests removal of a specific file. The server removes the file and responds with 204 No Content to confirm the action without a message body.
Request
DELETE /uploads/report.pdf HTTP/1.1
Host: api.example.re
Response
HTTP/1.1 204 No Content
REST API deletion with confirmation
A REST API returns 200 OK with a JSON body confirming the deletion and identifying the removed resource.
Request
DELETE /api/users/123 HTTP/1.1
Host: api.example.re
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
Response
HTTP/1.1 200 OK
Content-Type: application/json
{"deleted": true, "id": 123}
The Authorization header carries a bearer token because most APIs require Authentication before allowing destructive operations.
CORS
Cross-origin DELETE requests always trigger a CORS preflight. The browser sends an OPTIONS request first to confirm the server allows DELETE on the target resource.
Request and response body
DELETE requests may include a body, but the semantics are undefined. Some intermediaries reject DELETE requests with bodies due to request smuggling risks. Most APIs do not use a request body for DELETE. When a body is needed, such as for bulk deletion, the server defines the expected format.
The response body depends on the status code. A 200 OK response includes a body describing the result or returning the deleted resource. A 204 No Content response confirms deletion with no body. A 202 Accepted response indicates the deletion is queued or in progress and typically includes a reference to a status monitor.
Response status codes
204 No Content is the most common response for straightforward deletions where no body is needed. 200 OK is appropriate when the server returns the deleted resource or a confirmation message in the response body.
202 Accepted signals that the deletion is queued or asynchronous. The response typically includes a Location header or body pointing to a status endpoint where the client checks progress.
Subsequent requests to a deleted resource return 404 Not Found or 410 Gone. A 410 response indicates the resource existed previously and was intentionally removed, while 404 makes no such distinction.