Planteamiento y contexto
Una API en línea debe trasladar la ruta de su recurso de forma permanente de /v1/orders a /v2/orders. Quienes realizan las llamadas incluyen formularios de navegador, clientes móviles, SDK de terceros y workers asíncronos; las solicitudes pueden ser POST con cuerpos JSON grandes y una clave de idempotencia. Diseña los códigos de estado, el comportamiento del cliente, la observabilidad y la ruta de rollback para la migración.
Esta pregunta evalúa si puedes aplicar la semántica de redirección con precisión y evitar efectos secundarios duplicados durante el traslado de una API. RFC 9110 define 308 Permanent Redirect; MDN explica que un cliente no debe cambiar el método original ni el cuerpo de la solicitud al reenviarla a la nueva ubicación. 301 es permanente, pero los clientes históricos presentan diferencias de compatibilidad para solicitudes que no son GET y pueden cambiar el método.
Qué evalúa el entrevistador
El entrevistador quiere que distingas entre traslados permanentes y temporales, y que luego preguntes si se requiere preservar el método y el cuerpo. Una respuesta sólida compara 301, 302, 307 y 308, explica por qué un POST con efectos secundarios no puede depender de que un cliente adivine cómo reintentar, e incluye claves de idempotencia, autenticación, tiempos de espera (timeouts) y rollback.
También esperan que consideres el límite de confianza del encabezado Location, las credenciales de origen cruzado (cross-origin), la propagación de la caché, los límites de redirección de los SDK y los clientes que no admiten 308. Recitar que «308 es 301 más preservación de POST» sin un plan de pruebas de migración es incompleto.
Aclaraciones que conviene hacer primero
Permanencia y alcance
Confirma que la nueva URL sea estable y si el traslado abarca un solo recurso, un prefijo de API o un origen diferente. Si el destino aún puede cambiar, utiliza 307 para expresar un traslado temporal en lugar de inculcar prematuramente a clientes e intermediarios una semántica de caché permanente.
Capacidad del cliente y efectos secundarios
Enumera navegadores, versiones móviles, SDK, consumidores de colas y socios. Pregunta si el método POST crea un pedido, cobra dinero o emite un mensaje, y si los emisores envían una clave de idempotencia. Sin evidencia de que la repetición sea segura, una redirección no es una instrucción incondicional de reintento.
Credenciales, cachés y rollback
Confirma el alcance de la autenticación, CORS, los proxies y el comportamiento de la CDN para ambos hosts. Pregunta si el endpoint antiguo puede seguir prestando servicio y si el rollback significa eliminar la redirección, cambiar el enrutamiento o restaurar el handler antiguo.
Una respuesta de 30 segundos
«Primero confirmaría si el traslado es permanente e inventariaría cada cliente. Para un traslado permanente que deba preservar el método y el cuerpo de un POST, usaría 308; un traslado temporal usa 307. Un 301 no es un contrato estricto para preservar la semántica que no sea GET en clientes históricos. Inicialmente haría de proxy desde el endpoint antiguo hacia el nuevo handler, reutilizaría una sola clave de idempotencia para cada efecto secundario y restringiría el host de Location y el reenvío de credenciales. Durante un despliegue canary monitorearía la tasa de seguimiento de 3xx, creaciones duplicadas, 4xx/5xx, tamaño del cuerpo y versión del SDK. Si las métricas empeoran, dejaría de enviar 308 y mantendría el endpoint antiguo con capacidad de servicio».
Análisis detallado paso a paso
Paso 1: Elegir el código de estado con precisión
308 indica un traslado permanente y preserva el método y el cuerpo de la solicitud; 307 es temporal y también los preserva. 301 es permanente, pero no todos los clientes históricos preservan métodos como POST, por lo que no es un contrato estricto para la migración de un POST. 302 tampoco debería ofrecer esa garantía.
Paso 2: Tratar la repetición como la restricción principal
Debido a que 308 puede provocar que un cliente envíe el cuerpo completo nuevamente, ambos endpoints deben reconocer el mismo comando de negocio mediante la misma clave de idempotencia. Antes de ejecutar un efecto secundario, el servidor valida la clave contra un digest de la solicitud; la misma clave con parámetros diferentes se convierte en un conflicto en lugar de un segundo pedido. Un cliente sigue respetando su presupuesto de reintentos tras un timeout y no debe seguir 308 indefinidamente.
Paso 3: Lanzar en fases y observar
Haz que la nueva dirección funcione directamente antes de enrutar la dirección antigua a través de un proxy observable o una respuesta 308. Realiza un despliegue canary por versión del SDK, origen de la fuente y método. Registra la longitud de la cadena de redirecciones, fallos al seguir la redirección, efectos secundarios duplicados, latencia del destino, fallos de autenticación y tamaño del cuerpo. Para los clientes que no admiten 308, mantén un proxy del lado del servidor de corta duración en lugar de cambiar silenciosamente a 301 y asumir un comportamiento equivalente.
Paso 4: Gestionar la seguridad, el almacenamiento en caché y el rollback
Location solo puede apuntar a un destino en lista de permitidos. Vuelve a evaluar cookies, Authorization y CORS antes de un salto entre orígenes distintos para que las credenciales no lleguen a un host no confiable. Define explícitamente la ventana de caché de la CDN y del cliente, comenzando con un período corto durante la validación y ampliándolo gradualmente. En caso de rollback, deja de emitir nuevas redirecciones y permite que el endpoint antiguo acepte las mismas claves de idempotencia; los resultados ya escritos en el nuevo endpoint no pueden "deshacerse" simplemente revirtiendo las rutas.
Una respuesta de ejemplo de alta calidad
Trataría esto como un problema de protocolo y migración, no como un ejercicio de elegir un número. Para un traslado permanente donde se deban preservar el método y el cuerpo de un POST, elijo 308; para un desvío temporal de tráfico, elijo 307. 301 es adecuado para muchos traslados de URL de páginas, pero no ofrece la garantía estricta de preservación de método que necesito para una API que no sea GET.
Antes del despliegue, ambas URL admiten la misma autenticación, validación de solicitudes y contrato de claves de idempotencia. El endpoint antiguo primero actúa como proxy hacia el nuevo handler con registros completos, y la misma clave más el digest de la solicitud solo pueden producir un efecto secundario. Luego realizo un despliegue canary de 308 por versión de cliente, restrinjo el host de destino, vuelvo a verificar las credenciales de origen cruzado y compruebo el comportamiento de la CDN, el SDK y los consumidores de colas.
Monitoreo la tasa de seguimiento de redirecciones, la longitud de la cadena, las creaciones duplicadas, los errores en el destino, los fallos de autenticación y el tamaño del cuerpo. Si un cliente antiguo no comprende 308, mantengo el proxy en el endpoint antiguo en lugar de degradar silenciosamente a 301. Durante un incidente, detengo el 308, preservo el endpoint antiguo y los registros de idempotencia, restauro el enrutamiento y concilio los resultados de negocio completados mediante el ID de solicitud.
Errores comunes
- Devolver 301 para cada traslado → Los clientes históricos pueden cambiar POST a otro método o descartar el cuerpo → Usa 308 para un traslado permanente de API que requiera preservación y luego verifica los clientes.
- Ejecutar el efecto secundario nuevamente tras ver 308 → Las redirecciones, los timeouts y los reintentos de los clientes pueden multiplicar una solicitud de creación → Usa una clave de idempotencia, digest de la solicitud y un presupuesto de reintentos acotado.
- Tratar 307 como permanente → Un estado temporal puede volverse persistente en cachés o configuraciones de SDK, dificultando el rollback → Usa 307 para desvíos temporales y decide usar 308 solo tras la estabilización.
- Ignorar el riesgo de Location entre orígenes distintos → Las cookies o el encabezado Authorization pueden llegar a un destino no confiable → Valida conjuntamente una lista de permitidos, la política de credenciales y CORS.
- Monitorear únicamente el conteo de 3xx → Los fallos de seguimiento en SDK antiguos y las escrituras duplicadas permanecen invisibles → Cruza la tasa de seguimiento, los errores y los resultados de los efectos secundarios por versión del cliente.
Preguntas de seguimiento
Pregunta de seguimiento 1: ¿Por qué no devolver 200 desde la URL antigua y mencionar la nueva URL en el cuerpo?
Eso no permite que los clientes genéricos, cachés o SDK migren automáticamente, y no expresa que el recurso se trasladó de forma permanente. Puede mantenerse un proxy del lado del servidor durante la transición, pero el contrato de migración aún necesita un estado explícito y el encabezado Location mientras se registra si los emisores realmente cambiaron.
Pregunta de seguimiento 2: ¿Puede 308 reenviar Authorization sin cambios a un nuevo host?
No por defecto. Primero se debe establecer que ambos hosts comparten un límite de confianza; de lo contrario, haz que el cliente obtenga o envíe explícitamente las credenciales para el host de destino. El servidor debe rechazar valores de Location controlados por el usuario para evitar redirecciones abiertas y fugas de credenciales.
Pregunta de seguimiento 3: ¿Qué sucede si un cliente antiguo no admite 308 en absoluto?
Mantén un proxy del lado del servidor para el endpoint antiguo o devuelve una respuesta de compatibilidad según la capacidad conocida del cliente hasta que la versión antigua deje de usarse. El proxy debe reutilizar la clave de idempotencia de la solicitud y tener una fecha de retiro; no se puede asumir sin evidencia que todo cliente tratará a 308 como 301.
Pregunta de seguimiento 4: ¿El rollback consiste simplemente en cambiar 308 de nuevo a 200?
También se deben conciliar pedidos, eventos y registros de auditoría ya escritos por el nuevo endpoint. Detén las nuevas redirecciones y restaura el punto de entrada antiguo, luego haz que ambas rutas lean la misma fuente de verdad para que las escrituras no se bifurquen ni se dupliquen. Verifica los efectos secundarios completados mediante el ID de solicitud y la clave de idempotencia una vez restaurado el enrutamiento.