Entrevista de Backend: ¿Cuándo debería una API devolver 204 No Content?

Planteamiento y alcance

Diseñe un contrato de respuesta vacía para una API REST. ¿Cómo debería responder una eliminación exitosa? ¿Debería una consulta de colección sin coincidencias devolver 204? ¿Qué debería devolver una actualización exitosa cuando no se necesita ninguna representación? Separe un recurso inexistente, una operación exitosa sin representación, una operación asíncrona y una colección vacía válida. Suponga clientes generados en varios lenguajes y un contrato de larga duración.

Qué está evaluando el entrevistador

Trate los códigos de estado como semántica de recursos, no como un atajo para "no hay datos". 204 significa éxito sin contenido de mensaje y no debe incluir un cuerpo de mensaje; 200 puede devolver una representación estable como []; 404 significa que el recurso de destino está ausente o no tiene una representación actual. Analice la idempotencia de DELETE, cachés, decodificación de SDK y documentación de OpenAPI.

Aclaraciones antes de responder

1. ¿Cuál es el destino? Eliminar un recurso, actualizar un recurso y consultar una colección tienen semánticas diferentes.
2. ¿Es una colección vacía un resultado normal? En caso afirmativo, 200 con [] suele preservar un tipo de respuesta estable mejor que 204.
3. ¿Deben los clientes decodificar una estructura JSON única? Un cliente generado que siempre lee un cuerpo puede transformar un 204 en un EOF inesperado a menos que tenga una bifurcación explícita.
4. ¿Requiere el éxito una nueva representación, ETag o ID de trabajo asíncrono? Si es así, conserve un cuerpo de respuesta y elija 200, 201 o 202.

Decisión recomendada y derivación

Defina el contrato según la operación y la necesidad de representación:

• Un DELETE /users/42 exitoso sin representación que devolver puede usar 204. Si la eliminación repetida se define como éxito idempotente, también puede permanecer en 204, pero documéntelo.
• Si GET /users?team=none encuentra una colección existente sin elementos, devuelva 200 y [] para preservar el tipo de lista; cero filas no son un recurso inexistente.
• Si GET /users/42 no puede encontrar el destino, devuelva 404. Esa es semántica de recurso de destino, no semántica de lista vacía.
• Si PUT /users/42 tiene éxito y el cliente necesita la nueva representación, devuelva 200 con JSON. Si no se necesita ninguna representación, 204 es válido y ETag aún puede transportar metadatos.
• Si la solicitud se acepta pero el trabajo continúa, devuelva 202 con un enlace al estado de la tarea en lugar de disfrazarlo de 204.

HTTP/1.1 204 No Content
ETag: "user-42-v7"
Cache-Control: no-store

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

[]

RFC 9110 define 204 como no tener contenido de mensaje, por lo que los clientes, proxies y pruebas deben tratar la ausencia de cuerpo como parte del contrato. No coloque errores de negocio dentro de un 200 exitoso solo por uniformidad, y no convierta cada resultado vacío en 204 para ahorrar unos pocos bytes.

Alternativas y compensaciones

Un 200 con arreglo vacío mantiene los tipos estables, es fácil de manejar para SDK generados y puede transportar metadatos de paginación; cuesta unos pocos bytes. 204 expresa claramente el éxito sin una representación, adaptándose a DELETE o a una actualización que no repite datos; los clientes deben manejar un cuerpo ausente y no pueden leer detalles de error allí. Reserve 404 para un recurso de destino inexistente en lugar de una colección vacía válida.

Modos de falla, límites y contraejemplos

• Devolver 204 para una lista GET vacía hace que los clientes traten un resultado vacío válido como un tipo de respuesta diferente, rompiendo la paginación y la decodificación genérica.
• Enviar un cuerpo JSON con 204 viola la semántica de su mensaje; los proxies pueden descartarlo y los clientes divergirán.
• Devolver 204 en el primer DELETE y 404 en un reintento sin documentar la idempotencia genera errores de reintento evitables.
• Devolver 200 con { "error": ... } hace que la monitorización y los SDK clasifiquen un fallo de negocio como éxito.
• Devolver 204 tras una actualización que necesita un nuevo ETag pero omitir el encabezado de respuesta impide el almacenamiento en caché seguro o el control de concurrencia.

Lista de verificación de pruebas y verificación

Escriba pruebas de contrato para el estado, cuerpo, Content-Type, ETag y encabezados de caché en cada endpoint. Cubra DELETE inicial y repetido, colecciones vacías, recursos individuales faltantes, actualizaciones con y sin representaciones, la bifurcación asíncrona 202, reenvío de proxies y decodificación de SDK. Genere al menos un cliente desde OpenAPI y verifique que 204 no desencadene errores de análisis sintáctico de JSON; compruebe que la monitorización separe 2xx, 404 y errores de negocio estructurados.

Preguntas de seguimiento

¿Puede 204 transportar un ETag u otros encabezados de respuesta?

Sí. Prohibir el contenido del mensaje no prohíbe los metadatos. ETag, controles de caché o un trace ID pueden admitir el control de concurrencia y el diagnóstico, pero documente cuándo están presentes.

¿Debería una página vacía ser 200 o 204?

Si la representación es una lista, prefiera 200 con un arreglo vacío y metadatos de paginación. Considere 204 solo cuando el "éxito sin representación" sea explícito y cada cliente maneje un cuerpo ausente.

¿Debe DELETE devolver 404 cuando el recurso no existe?

No siempre. Si la eliminación significa "asegurar que el recurso esté ausente", las solicitudes repetidas pueden devolver 204. Si los llamadores necesitan saber si existía, devuelva 404. Registre la elección de manera consistente en la documentación, los SDK y la monitorización.