Planteamiento y alcance
El proveedor desea eliminar /v1/items tras una ventana de migración, pero los clientes pertenecen a diferentes equipos y algunos están inactivos. Suponga que el proveedor puede observar las solicitudes por identidad de cliente y puede ejecutar /v2/items en paralelo. El plan debe distinguir un anuncio de obsolescencia de una fecha de eliminación, conservar un mecanismo de respaldo seguro y evitar asumir que un encabezado por sí solo migra a los clientes.
Qué evalúa el entrevistador
- Separación de señales de protocolo, documentación, inventario de clientes y aplicación obligatoria.
- Diseño de compatibilidad aditiva y un criterio de migración medible.
- Manejo de clientes desconocidos, integraciones de larga duración y reversión de emergencia.
- Selección de códigos de estado y encabezados sin inventar semánticas fuera de los estándares.
Preguntas de aclaración para hacer
Pregunte si los clientes envían una identidad estable, si /v2 puede ser aditivo, el período mínimo de soporte, los requisitos contractuales de notificación y si el endpoint antiguo puede configurarse como de solo lectura antes de su eliminación. Si falta la identidad, la evidencia de migración debe provenir de credenciales, metadatos de red o registro explícito, en lugar de agentes de usuario supuestos.
La respuesta de 30 segundos
Crearía un inventario de los clientes que llaman a la API, publicaría una guía de migración versionada, lanzaría /v2 de forma aditiva y mediría el tráfico por cliente y la paridad de errores. Marcaría /v1 con la señal estandarizada de Deprecation y una fecha de Sunset, al tiempo que expondría un panel de control y avisos directos para los propietarios conocidos. Mantendría la ruta antigua durante una ventana determinada, aplicaría el bloqueo obligatorio solo tras una validación basada en evidencia y devolvería una respuesta terminal documentada con un enlace de migración. Un feature flag y un enrutamiento reversible permitirían la reversión si un cliente crítico falla.
Análisis detallado paso a paso
1. Establecer compatibilidad y evidencia
Defina las diferencias a nivel de campo, el comportamiento por defecto, la paginación, los errores y los cambios de autenticación. Ejecute pruebas de contrato contra ambas versiones y compare respuestas representativas. Etiquete las métricas por cliente, versión, endpoint, estado y estado de migración; no utilice únicamente el tráfico agregado, ya que un cliente de bajo volumen puede ser crítico para el negocio.
2. Señalizar la obsolescencia con precisión
El encabezado de respuesta Deprecation comunica que un recurso está obsoleto; el encabezado Sunset comunica una fecha planificada a partir de la cual puede dejar de estar disponible. Son señales, no una garantía de que todos los clientes las entiendan. Reitere la fecha en la documentación y en las notificaciones a los propietarios, e incluya una referencia de migración estable en el cuerpo de la respuesta o en la relación de enlace definida por el contrato de la API.
3. Migrar y aplicar de forma escalonada
Comience con advertencias y paneles de control, y luego exija excepciones explícitas para los clientes que no cumplan el plazo objetivo. Ofrezca comparaciones en la sombra (shadow) o tráfico opcional por suscripción (opt-in) antes de cambiar los valores predeterminados. En la fase de aplicación obligatoria, rechace únicamente la operación antigua que sea seguro retirar, devuelva un error legible por máquina y conserve una vía de soporte. La compatibilidad de solo lectura se puede extender por más tiempo que la compatibilidad con mutaciones cuando el riesgo difiere.
4. Mantener la reversión y la gobernanza reales
Guarde la fecha de sunset, el propietario, el motivo de la excepción y la aprobación en un registro de cambios. Configure alertas para las diferencias de error posteriores a la migración y las solicitudes de clientes desconocidos. Enrute la ruta antigua a través de un feature flag para que la reversión sea un cambio de configuración y no un nuevo despliegue de código. Tras la eliminación, conserve la telemetría y una respuesta de lápida (tombstone) el tiempo suficiente para explicar el error sin exponer secretos.
Un buen ejemplo de respuesta
Crearía un inventario de 10.000 clientes y definiría las diferencias exactas de contrato entre /v1 y /v2. Ambas versiones se ejecutarían en paralelo con métricas por cliente y pruebas de contrato. Las respuestas de /v1 incluirían señales de Deprecation y Sunset, mientras que la documentación y los avisos a los propietarios reiterarían la fecha y los pasos de migración. El proveedor avanzaría a través de fases de advertencia, opt-in, cambio por defecto a v2 y aplicación obligatoria, con excepciones explícitas y un error terminal legible por máquina. Un feature flag mantendría la posibilidad de reversión; el criterio de sunset se basaría en evidencia a nivel de cliente, no en un porcentaje de tráfico agregado.
Errores comunes
- Asumir que un encabezado realiza la migración → muchos clientes lo ignoran → combine las señales estándar con el descubrimiento de propietarios y una guía.
- Establecer una fecha sin un inventario → clientes inactivos pero críticos fallan inesperadamente → exija identidad de cliente y revisión de excepciones.
- Comparar solo tasas de error agregadas → la interrupción de un inquilino desaparece en el promedio → supervise la paridad y el volumen por cliente.
- Eliminar inmediatamente después del lanzamiento de
/v2→ los clientes no tienen pruebas de compatibilidad → ejecute primero fases en paralelo o de opt-in. - Hacer que la reversión requiera un nuevo despliegue → la recuperación es lenta durante una interrupción → enrute las versiones detrás de un flag reversible.
- Devolver un 404 no documentado en el sunset → la automatización no puede distinguir la eliminación de un error tipográfico → publique un error terminal estable y una referencia de migración.
Preguntas de seguimiento y respuestas
Un cliente nunca envía un encabezado de identificación. ¿Cuál es el criterio de migración?
Utilice la credencial, la cuenta, la red o la identidad de registro que ya esté disponible para el proveedor. Si ninguna es confiable, mantenga el endpoint disponible por más tiempo y exija un registro explícito antes de la aplicación obligatoria.
¿Se puede mover la fecha de Sunset?
Sí, si el registro de cambios, la documentación, los encabezados y los avisos a los propietarios se actualizan juntos. Trate la fecha como un compromiso de gobernanza y alerte sobre los clientes que aún dependen de la ruta antigua.
¿Qué sucede si /v2 es correcto pero más lento para un cliente?
Compare la latencia y el presupuesto de errores del cliente por separado y, a continuación, optimice o conceda una excepción por tiempo limitado. No extienda la ventana de sunset de toda la población sin evidencia de que el problema sea sistémico.
¿Cómo se retira un endpoint mutador de forma segura?
Detenga las nuevas escrituras después de la validación basada en evidencia, conserve el acceso de lectura cuando sea posible y haga que los reintentos devuelvan un error terminal determinista. Confirme que las colas downstream y los registros de auditoría ya no dependan de la mutación antigua antes de la eliminación.