DELETE

Uso

Una solicitud DELETE indica al servidor que elimine el recurso de destino. El servidor determina qué significa la eliminación en la práctica: el recurso puede borrarse de forma permanente, archivarse o marcarse como inactivo.

Las API REST dependen en gran medida de DELETE para representar la destrucción de recursos. Un endpoint de API como DELETE /api/users/123 expresa con claridad la intención de eliminar el registro de usuario identificado por 123. Esto se corresponde directamente con el patrón PUT/POST/GET/DELETE para las operaciones de creación, actualización, lectura y destrucción.

Los formularios HTML solo admiten GET y POST. Las API de JavaScript como fetch y XMLHttpRequest admiten DELETE de forma nativa. Algunos frameworks usan POST con un parámetro _method=DELETE como solución alternativa.

El servidor responde con uno de varios códigos de estado según el resultado:

Un borrado duro elimina el recurso de forma permanente. Las solicitudes GET posteriores devuelven 404 o 410 Gone. Un borrado lógico marca el recurso como inactivo sin eliminar los datos subyacentes. El recurso sigue siendo recuperable mediante una API de administración o con un parámetro de consulta. 410 comunica una eliminación permanente, mientras que 404 es apropiado cuando el recurso ya no existe en el URI.

Una solicitud DELETE es idempotente. Enviar la misma solicitud varias veces produce el mismo estado del servidor que enviarla una sola vez. La primera solicitud elimina el recurso y las siguientes no tienen ningún efecto adicional. Sin embargo, los códigos de respuesta pueden diferir: la primera solicitud devuelve 200 OK o 204 No Content, mientras que las posteriores devuelven 404 Not Found o 410 Gone.

Eliminar un recurso

Un cliente solicita la eliminación de un archivo concreto. El servidor elimina el archivo y responde con 204 No Content para confirmar la acción sin cuerpo de mensaje.

Solicitud

DELETE /uploads/report.pdf HTTP/1.1
Host: api.example.re

Respuesta

HTTP/1.1 204 No Content

Eliminación mediante API REST con confirmación

Una API REST devuelve 200 OK con un cuerpo JSON que confirma la eliminación e identifica el recurso eliminado.

Solicitud

DELETE /api/users/123 HTTP/1.1
Host: api.example.re
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

Respuesta

HTTP/1.1 200 OK
Content-Type: application/json

{"deleted": true, "id": 123}

La cabecera Authorization transporta un token bearer porque la mayoría de las API exigen autenticación antes de permitir operaciones destructivas.

CORS

Las solicitudes DELETE de origen cruzado siempre desencadenan una comprobación previa CORS. El navegador envía primero una solicitud OPTIONS para confirmar que el servidor permite DELETE sobre el recurso de destino.

Cuerpo de la solicitud y de la respuesta

Las solicitudes DELETE pueden incluir un cuerpo, pero su semántica no está definida. Algunos intermediarios rechazan las solicitudes DELETE con cuerpo por los riesgos de contrabando de solicitudes. La mayoría de las API no usan un cuerpo de solicitud para DELETE. Cuando se necesita un cuerpo, por ejemplo para eliminaciones masivas, el servidor define el formato esperado.

El cuerpo de la respuesta depende del código de estado. Una respuesta 200 OK incluye un cuerpo que describe el resultado o que devuelve el recurso eliminado. Una respuesta 204 No Content confirma la eliminación sin cuerpo. Una respuesta 202 Accepted indica que la eliminación está en cola o en curso y normalmente incluye una referencia a un monitor de estado.

Códigos de estado de respuesta

204 No Content es la respuesta más habitual para eliminaciones sencillas en las que no se necesita cuerpo. 200 OK es apropiado cuando el servidor devuelve el recurso eliminado o un mensaje de confirmación en el cuerpo de la respuesta.

202 Accepted indica que la eliminación está en cola o es asíncrona. La respuesta suele incluir una cabecera Location o un cuerpo que apunta a un endpoint de estado donde el cliente comprueba el progreso.

Las solicitudes posteriores a un recurso eliminado devuelven 404 Not Found o 410 Gone. Una respuesta 410 indica que el recurso existió previamente y se eliminó de forma intencionada, mientras que 404 no establece esa distinción.