Entrevista de Backend: ¿Cómo migrar una API de 200 JSON a 204?

1. Contexto y caso de uso

PATCH /profiles/42 ha estado en producción durante años. Cuando tiene éxito, devuelve 200 OK con un cuerpo fijo: { "success": true }. Una aplicación web, aplicaciones móviles, kits de desarrollo de software (SDK) de terceros y tareas de automatización lo consumen. El cuerpo no contiene datos de negocio, por lo que el equipo desea devolver 204 No Content en su lugar.

Cambiar la línea de estado es la parte sencilla. Un cliente antiguo podría llamar a response.json() para cada respuesta 2xx, un gateway podría extraer un campo del cuerpo y un panel de control podría contabilizar únicamente 200 como éxito. La migración debe permitir que los clientes antiguos y nuevos coexistan y proporcionar un rollback rápido del lado del servidor antes de que se propague un problema de compatibilidad.

2. Qué está evaluando el entrevistador

Si trata un cambio de estado como una migración de contrato de respuesta en lugar de una edición de una sola línea en el servidor.
Si incluye en el inventario a navegadores, aplicaciones móviles, SDKs, proxies, monitores y middleware de reintentos como consumidores reales.
Si puede ejecutar 200 y 204 de forma conjunta mediante versionado o negociación con Prefer.
Si define métricas de despliegue, condiciones de parada y un rollback del lado del servidor que no requiera degradar versiones de los clientes.
Si sabe que una respuesta 204 finaliza después de su sección de encabezados y no puede contener cuerpo ni trailers.

3. Preguntas a responder antes de la migración

¿Qué clientes siempre parsean JSON y cuáles solo inspeccionan response.ok o la clase 2xx?
¿Realmente no se lee el objeto de éxito, incluidos los recolectores de logs, scripts de gateway y tipos de retorno generados en los SDK?
¿Pueden los clientes reintentar automáticamente, convirtiendo una escritura exitosa seguida de un error de parseo en una solicitud duplicada?
¿Es posible actualizar todos los clientes o deben permanecer disponibles ambos contratos durante un período prolongado?
¿Qué encabezados, como ETag, campos de límite de tasa (rate-limit) e identificadores de rastreo, deben conservarse?

4. Estructura de respuesta de 30 segundos

Primero crearía un inventario de consumidores y utilizaría pruebas de contrato para identificar cada dependencia respecto al cuerpo JSON de la respuesta 200. Durante la migración, 200 se mantiene como el valor por defecto. Los clientes compatibles optan por la respuesta mínima a través de una nueva versión de la API o mediante Prefer: return=minimal; cuando el servidor la acepta, devuelve 204 y reporta Preference-Applied. Realizaría el despliegue progresivo desde el tráfico interno hacia versiones de clientes conocidas de bajo riesgo, monitoreando fallos de parseo, escrituras duplicadas, reintentos y la tasa de éxito por cliente. El rollback consiste en un cambio en el servidor de regreso a 200, ya que la ruta de serialización JSON se mantiene intacta hasta que concluye la migración.

5. Plan de migración por etapas

Paso 1: Crear un inventario de capacidades de los clientes

Para cada cliente, registre su propietario, versión, biblioteca HTTP, validación de éxito, parser de respuesta y política de reintentos. Busque llamadas incondicionales a response.json(), comparaciones exactas con status === 200, tipos de retorno generados en SDKs y lecturas de body.success en gateways. Los clientes desconocidos o sin versión permanecen en 200. Si no hay evidencia de compatibilidad, no se despliega 204.

Paso 2: Hacer que los clientes acepten ambos contratos de éxito

Entregue primero el soporte en los clientes. Un cliente compatible acepta las respuestas 2xx acordadas, verifica si recibe 204 o un cuerpo vacío antes de parsear, y separa el éxito de la solicitud de la decodificación del JSON. Las pruebas de contrato le suministran tanto 200 + JSON como 204 + empty body. Invertir este orden corre el riesgo de convertir una escritura exitosa en un fallo de parseo visible para el cliente y, consecuentemente, en un reintento duplicado.

Paso 3: Elegir cómo coexistirán los dos contratos

Para un cambio incompatible deliberado, una nueva versión de la API puede devolver siempre 204 mientras la versión anterior mantiene 200. Si la ruta y la operación siguen siendo las mismas, la negociación de preferencias según RFC 7240 es otra opción: los clientes compatibles envían Prefer: return=minimal; el servidor puede responder con 204 y Preference-Applied: return=minimal. Los clientes que necesitan la representación envían Prefer: return=representation o mantienen el comportamiento predeterminado 200. Si la respuesta es almacenable en caché, declare Vary: Prefer correctamente.

Paso 4: Desplegar por cliente, no por solicitud aleatoria

Habilite el comportamiento primero en entornos de prueba y clientes internos, luego expándalo únicamente a las versiones de clientes confirmadas como compatibles. Mantenga cada cliente o cuenta en una cohorte estable para que no alterne entre 200 y 204. Observe un ciclo de negocio completo en cada etapa antes de expandir; un período corto con métricas HTTP limpias no es suficiente.

Paso 5: Observar los fallos que puede ocasionar el cambio de protocolo

En el servidor, desglose los conteos de 200, 204, 5xx y reintentos por versión de cliente. En los clientes, registre fallos de parseo por cuerpo vacío, interfaces de usuario con error tras una solicitud exitosa y envíos duplicados. Compare las escrituras completadas con los reintentos de solicitudes, especialmente en operaciones no idempotentes. Las alertas deben identificar la versión del cliente y la cohorte de despliegue; las tasas agregadas de 2xx ocultan los fallos de compatibilidad.

Paso 6: Preservar el rollback instantáneo y finalizar la migración

Mantenga la ruta original de serialización JSON detrás del interruptor del servidor durante toda la migración. Si se activa una condición de parada, restablezca 200 a nivel global; los clientes con compatibilidad dual seguirán funcionando sin requerir una degradación. Elimine la ruta antigua solo después de que todos los clientes soportados superen la versión mínima compatible, no haya presencia de tráfico antiguo durante una ventana de observación acordada y las suites de pruebas de SDKs, proxies y contratos sigan pasando.

6. Ejemplo de respuesta de alta calidad

Trataría esto como una migración de contrato de respuesta. Primero haría un inventario de cada consumidor para encontrar código que siempre parsee JSON, valide exactamente 200 o lea body.success. Lanzaría clientes que acepten tanto 200 JSON como 204 sin cuerpo antes de modificar el comportamiento del servidor. El servidor mantendría 200 como el valor por defecto; los clientes compatibles seleccionarían 204 a través de una versión de API o Prefer: return=minimal, confirmado mediante Preference-Applied. El despliegue avanzaría por versión de cliente, utilizando los fallos de parseo, reintentos y escrituras duplicadas como señales primarias. La ruta de serialización 200 permanecería disponible hasta que todos los clientes soportados hayan migrado, de modo que el rollback sea un interruptor del lado del servidor y no un despliegue de clientes.

7. Errores comunes

Cambiar 200 directamente a 204 → los clientes antiguos fallan al parsear un cuerpo vacío → lance clientes con compatibilidad dual antes de habilitar 204.
Observar solo las tasas de error HTTP → 204 sigue siendo una respuesta exitosa, por lo que los fallos de parseo no aparecen como errores 5xx del servidor → agregue métricas de parseo del cliente, reintentos y escrituras duplicadas.
Aleatorizar el despliegue por solicitud → un cliente recibe un contrato inestable → agrupe por versión de cliente u otra identidad estable.
Aceptar Prefer sin reportar el resultado → el cliente no puede determinar si se respetó la preferencia → devuelva Preference-Applied y defina el comportamiento por defecto.
Eliminar la serialización JSON de inmediato → el rollback requiere un despliegue de código → conserve la ruta antigua hasta que concluya la ventana de migración.
Ignorar el comportamiento de reintento automático → un error de parseo disfraza una escritura exitosa como un fallo → verifique claves de idempotencia, middleware de reintentos y métricas de envíos duplicados.

8. Preguntas de seguimiento y respuestas

Pregunta de seguimiento 1: ¿Por qué no migrar todos los clientes a la vez?

El servidor puede comprobar que la escritura fue exitosa, pero no puede garantizar que cada cliente desplegado maneje un cuerpo 204 correctamente. Una sola versión antigua que siempre parsee JSON convierte el éxito a nivel de protocolo en una falla visible para el usuario. Priorizar la compatibilidad del cliente, seguido de un despliegue acotado por versión, mantiene observable el límite de fallos.

Pregunta de seguimiento 2: ¿Cuándo se debe elegir versionado frente a Prefer?

Una nueva versión se adapta a un cambio de contrato permanente y es fácil de razonar, pero añade trabajo de gestión del ciclo de vida de versiones. Prefer se adapta a una operación en la que tanto una representación de retorno como una respuesta mínima son válidas. Dado que un servidor puede ignorar una preferencia, el cliente necesita un comportamiento por defecto documentado y debe inspeccionar Preference-Applied. Ambos enfoques son más confiables que deducir capacidades a partir de cadenas de User-Agent.

Pregunta de seguimiento 3: ¿Qué información puede retener una respuesta 204?

Puede retener encabezados como ETag, identificadores de rastreo y campos de límite de tasa (rate-limit). No puede transportar contenido del mensaje ni trailers. Por lo tanto, un cliente debe tratar "sin JSON" y "sin metadatos" como conceptos independientes.

Pregunta de seguimiento 4: ¿Cuándo es seguro eliminar la ruta de compatibilidad 200?

Todos los clientes soportados deben haber implementado el manejo de respuesta dual, la telemetría no debe mostrar tráfico de versiones antiguas y las pruebas de SDKs, proxies, automatización y rollback deben pasar con éxito. Un lanzamiento en la tienda de aplicaciones por sí solo no es suficiente, ya que los usuarios pueden permanecer en versiones antiguas durante un largo período de tiempo.