DELETE - Remove Recurso

1. Definição e Semântica

O método HTTP DELETE é definido pela RFC 7231 (seção 4.3.5) como o método que solicita a remoção do recurso identificado pela URL alvo. Sua semântica é de "remove": o servidor deve apagar o recurso ou marcá-lo como removido, de forma que requisições subsequentes ao mesmo recurso indiquem ausência (tipicamente 404 Not Found).

Características Formais

• Método: DELETE
• Seguro: Não (modifica estado do servidor)
• Idempotente: Sim (deletar o mesmo recurso 1 ou 100 vezes leva ao mesmo estado: inexistente)
• Cacheável: Não (por padrão)
• Corpo na requisição: Opcional (não recomendado; alguns servidores ignoram)
• Corpo na resposta: Opcional
• RFC de referência: RFC 7231 §4.3.5 (obsoleta por RFC 9110)

Idempotência

DELETE é idempotente por definição. A primeira chamada remove o recurso; chamadas subsequentes encontram o recurso inexistente e tipicamente retornam 404 Not Found. O estado final do servidor é o mesmo: o recurso não existe. Isso garante segurança em retries.

DELETE /users/42 HTTP/1.1
Host: api.exemplo.com
Authorization: Bearer eyJ...

2. Soft Delete vs Hard Delete

Hard Delete

Remoção física do registro do banco de dados. Após o DELETE, o recurso desaparece completamente. Não há como recuperar.

DELETE FROM users WHERE id = 42;

Vantagens: libera espaço imediatamente, sem resíduos.
Desvantagens: irreversível; em caso de erro ou auditoria, o dado está perdido.

Soft Delete

Marca o recurso como removido (ex: deleted_at = NOW() ou flag is_active = false), sem apagar fisicamente. Requisições subsequentes retornam 404 para o cliente, mas o registro continua no banco.

UPDATE users SET deleted_at = NOW() WHERE id = 42;

Vantagens: recuperável, permite auditoria, mantém integridade referencial.
Desvantagens: requer filtragem em todas as queries (WHERE deleted_at IS NULL), acumula dados órfãos.

Boas Práticas

• APIs públicas: soft delete quase sempre, com política de expurgo (ex: hard delete após 90 dias).
• APIs administrativas: hard delete para dados sensíveis (LGPD/GDPR right to erasure).
• Bancos distribuídos: soft delete com campo deleted_at permite sincronização e recuperação tardia.

3. Códigos de Resposta Típicos

Convenção de Status

A escolha entre 200, 202 e 204 depende do contrato da API:

• 200 OK com corpo: cliente recebe confirmação com dados do recurso removido (ex: {"deleted": true, "id": 42}).
• 204 No Content: resposta vazia, mais econômica. Padrão comum em APIs REST modernas.
• 202 Accepted: usado em operações longas (ex: deletar usuário com milhares de registros relacionados). Cliente deve fazer polling de status ou aguardar webhook.

4. Autorização e Segurança

Autenticação Obrigatória

DELETE sempre deve exigir autenticação. Sem token/cookie válido, retornar 401 Unauthorized.

Autorização Granular

Mesmo autenticado, o cliente pode não ter permissão para deletar o recurso:

• Usuário comum: só pode deletar seus próprios recursos.
• Admin: pode deletar qualquer recurso.

Retornar 403 Forbidden quando o usuário autenticado tenta deletar recurso de terceiro.

CSRF Protection

DELETE via navegador (com cookies de sessão) está sujeito a CSRF. Mitigações:

• Token CSRF em header customizado (X-CSRF-Token).
• SameSite cookies (SameSite=Strict ou Lax).
• CORS estrito: permitir DELETE apenas de origens confiáveis.
• Custom header requirement: browsers só permitem headers customizados com preflight CORS, que bloqueia CSRF simples.

Confirmação do Cliente

Para recursos críticos (ex: deletar conta), exigir confirmação adicional: senha atual, token TOTP ou 2FA via SMS/email.

5. Headers Importantes

Authorization

Padrão para APIs REST (Bearer token JWT): Authorization: Bearer eyJhbGc....

If-Match

Concorrência otimista via ETag:

DELETE /users/42 HTTP/1.1
If-Match: "abc123"

Retorna 412 Precondition Failed se a ETag atual do recurso não casar (alguém modificou antes).

If-Unmodified-Since

Concorrência baseada em tempo: If-Unmodified-Since: Wed, 21 Oct 2023 07:28:00 GMT.

6. Exemplos Práticos

curl — Deletar Recurso (204)

curl -X DELETE https://api.exemplo.com/users/42 \
  -H "Authorization: Bearer $TOKEN" \
  -w "%{http_code}\n" -o /dev/null -s
# Saída: 204

curl — Deletar com If-Match

curl -X DELETE https://api.exemplo.com/users/42 \
  -H "Authorization: Bearer $TOKEN" \
  -H 'If-Match: "v3"'

Python (requests)

import requests
r = requests.delete(
    "https://api.exemplo.com/users/42",
    headers={"Authorization": "Bearer " + token},
)
if r.status_code == 204:
    print("Deletado com sucesso")
elif r.status_code == 404:
    print("Recurso não existe (idempotente)")

7. Boas Práticas em APIs REST

• Resposta consistente: Para 200 OK, retorne payload informativo {"deleted": true, "id": 42, "deleted_at": "2024-01-15T10:30:00Z"}. Para 204, resposta vazia.
• Soft delete com restauração: Exponha POST /users/42/restore para recuperar soft-deletados dentro da janela de tolerância.
• Idempotency-Key: Aceite header Idempotency-Key: 550e8400-... para evitar duplicações em retries.
• Auditoria: Log de DELETEs críticos (quem, quando, qual recurso, com qual IP). Necessário para conformidade LGPD/GDPR/SOC2.
• Rate limiting: Aplique rate limits por cliente para evitar abuso (ex: DELETE em massa).

8. Erros Comuns

9. Resumo Técnico

10. Conclusão

O método DELETE é o mecanismo HTTP padrão para remoção de recursos. Sua idempotência permite retries seguros, mas a decisão entre hard delete e soft delete depende de requisitos de negócio, conformidade e auditabilidade. Boas práticas como autenticação obrigatória, autorização granular, proteção CSRF, e uso de If-Match para concorrência otimista são essenciais. A escolha entre 200, 202 e 204 reflete o tipo de operação executada (síncrona com retorno, assíncrona, ou silenciosa) e deve ser documentada no contrato da API.