KAHIBARO
Discord Login Register ☰
☰

7.10. DELETE Requests

Table of Contents

When And How To Use DELETE Requests

DELETE requests are used in REST APIs to remove existing resources. They are one of the core HTTP methods for building CRUD style APIs and are usually mapped to the “Delete” operation.

In this chapter you will see how DELETE is used, what URLs it typically uses, what responses to return, and some important safety considerations.

What DELETE Is Used For

In REST, you usually have resources like users, posts, orders, and so on. A DELETE request is used to remove a specific resource.

Typical examples:

The key idea is that DELETE targets a specific resource, not “delete everything” unless your API explicitly allows bulk deletion.

Rule: Use DELETE to remove existing resources identified by a specific URL, for example
DELETE /resource/{id}

Typical RESTful DELETE URLs

The most common DELETE URLs follow the same pattern as GET for a single resource.

ActionMethodExample URL
Delete a userDELETE/users/123
Delete a productDELETE/products/987
Remove an item from a cartDELETE/carts/10/items/5

Avoid designs like:

The verb delete is already in the HTTP method. The URL should represent the resource, not the action:

Rule: URLs should be nouns (resources). Let the HTTP method represent the action.

Idempotence Of DELETE

DELETE is idempotent. This is an important property in HTTP.

Idempotent means:

Sending the same request multiple times has the same effect on the resource as sending it once.

For DELETE:

However, the responses can be different:

  1. First time:
http 
   DELETE /users/123
   204 No Content
  1. Second time:
http 
   DELETE /users/123
   404 Not Found

Still idempotent, because the resource is absent after both calls.

Rule: Repeating a DELETE must not keep deleting “more stuff”. After the first success, further DELETEs should leave the system state unchanged.

Typical DELETE Responses

DELETE responses usually use these status codes:

Status codeWhen to use
204 No ContentResource existed and was deleted, no response body is returned
200 OKDeleted and you return a body with extra info
202 AcceptedDeletion is asynchronous, will happen later
404 Not FoundResource does not exist
401 UnauthorizedClient is not authenticated
403 ForbiddenClient is authenticated but not allowed to delete
409 ConflictDeletion cannot happen due to conflict (for example constraints)

Most APIs choose between 204 and 200.

204 No Content example

Client:

http 
DELETE /posts/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>

Server:

http 
HTTP/1.1 204 No Content

No body is returned. The client just knows the deletion succeeded.

200 OK with response body

Sometimes you may want to return information about what was deleted.

http 
HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": 42,
  "title": "My Post",
  "deleted": true,
  "deleted_at": "2026-08-27T12:34:56Z"
}

Both patterns are valid. Many REST APIs prefer 204 No Content for DELETE for simplicity.

Rule: For a successful DELETE, prefer 204 No Content if you do not need to return any data.

Should DELETE Have A Body?

HTTP allows bodies with DELETE requests, but in practice most APIs do not use a body for DELETE.

Common patterns:

http 
  DELETE /users/123 HTTP/1.1
  Content-Type: application/json
  {
    "reason": "user_request"
  }

However, some HTTP clients and proxies do not handle DELETE bodies consistently. For simple beginner-friendly APIs, avoid DELETE request bodies.

Rule: Do not rely on a request body in DELETE calls unless you control all clients and infrastructure and know it is supported.

Soft Delete vs Hard Delete

“Delete” is not always as simple as removing a row from the database. Many systems use soft deletes.

Hard delete

Example SQL:

sql 
DELETE FROM users WHERE id = 123;

Soft delete

Example SQL:

sql 
UPDATE users
SET deleted_at = NOW()
WHERE id = 123;

From the API perspective, both operations use the same HTTP DELETE method. The difference is only on the backend implementation.

Example API behavior:

http 
DELETE /users/123
HTTP/1.1 204 No Content

The client does not need to know if you hard delete or soft delete, only that the user is no longer considered active.

You might also expose this information in an admin API:

http 
GET /admin/users/123
{
  "id": 123,
  "name": "Alice",
  "deleted_at": "2026-08-27T10:01:00Z"
}

Example DELETE Flows

1. Delete a blog post

Client:

http 
DELETE /posts/10 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>

Cases:

SituationResponse
User owns the post, post exists204 No Content
Post does not exist404 Not Found
Not logged in401 Unauthorized
Logged in but not the owner403 Forbidden

2. Remove an item from a cart

Client:

http 
DELETE /carts/5/items/2 HTTP/1.1
Host: shop.example.com
Authorization: Bearer <token>

Server:

http 
HTTP/1.1 200 OK
Content-Type: application/json
{
  "cart_id": 5,
  "removed_item_id": 2,
  "total_price": 49.90,
  "items_count": 3
}

Validation And Error Handling For DELETE

Even for DELETE, you should still validate input and handle errors clearly.

Common validation checks

Example:

http 
DELETE /orders/abc
HTTP/1.1 400 Bad Request
{
  "detail": "order_id must be an integer"
}

Example permission error:

http 
DELETE /projects/10
HTTP/1.1 403 Forbidden
{
  "detail": "You do not have permission to delete this project."
}

Example business rule:

http 
DELETE /orders/999
HTTP/1.1 409 Conflict
{
  "detail": "Order 999 is already shipped and cannot be deleted."
}

Rule: For DELETE, always check that the user is allowed to delete the resource, and return clear error codes like 401, 403, 404, or 409 when needed.

Safe Usage And Protection

DELETE is a dangerous operation from the perspective of data loss. You should protect it carefully.

Common safety practices:

  1. Authentication required
    Never allow anonymous DELETE of important resources.
  2. Authorization checks
    Only certain roles or the resource owner can delete.
  3. CSRF protection
    Especially for browser-based clients using cookies.
  4. Soft deletes
    So you can restore data if deleted by mistake.
  5. Rate limiting
    To avoid bots deleting many resources quickly.

Example: Deleting your own account

http 
DELETE /me
Authorization: Bearer <token>

Server side checks:

Idempotent Vs Safe Methods

In HTTP:

DELETE is idempotent but not safe, because it changes server state.

You should not perform DELETE requests automatically without user or system intention. For example, you should not delete a resource when a page is just loaded.

Small End To End Example

Consider a simple “tasks” API.

Create a task

http 
POST /tasks
Content-Type: application/json
{
  "title": "Buy milk"
}

Response:

http 
HTTP/1.1 201 Created
Content-Type: application/json
{
  "id": 1,
  "title": "Buy milk",
  "completed": false
}

Delete the task

http 
DELETE /tasks/1

Response:

http 
HTTP/1.1 204 No Content

Try to get it again

http 
GET /tasks/1

Response:

http 
HTTP/1.1 404 Not Found
Content-Type: application/json
{
  "detail": "Task not found."
}

This is a complete and typical flow for a DELETE in a REST API.

Summary

Views: 7

Comments

Please login to add a comment.

Don't have an account? Register now!

© 2025 Kahibaro
Visitors: 3491 / 24h
Impressum / Imprint
Datenschutz / Data Policy