Planteamiento y alcance
Una empresa retirará su API v1 en 12 meses y lanzará la v2. La v1 tiene 3000 clientes, cerca del 40 % de las solicitudes aún usan campos heredados y 200 clientes son empresas de altos ingresos. Planifica la migración equilibrando las nuevas capacidades, la compatibilidad, la experiencia del desarrollador, el riesgo de ingresos y el retiro de la versión.
Esto evalúa si un product manager puede transformar una migración técnica en un producto para el cliente delimitado: identificar quiénes se ven afectados, por qué el cambio es importante y qué comportamientos no deben romperse; para luego diseñar la compatibilidad, las herramientas, la comunicación, el despliegue escalonado y los criterios de salida. La guía de versiones de API de GitHub trata los cambios que rompen la compatibilidad, los encabezados Deprecation/Sunset, los períodos de soporte y las pruebas de migración como restricciones de gobernanza de versiones.
Qué evalúa el entrevistador
Primero, ¿puedes segmentar a los clientes y clasificar el riesgo en lugar de limitarte a anunciar una fecha única? Los clientes de altos ingresos, regulados, de baja actividad y de autoservicio presentan diferente resistencia a la migración.
Segundo, ¿puedes distinguir entre compatibilidad, migración y retiro? Mantener una versión antigua, añadir un adaptador o proporcionar una conversión por lotes reduce el riesgo, pero no reemplaza la confirmación del cliente ni un estándar de salida.
Tercero, ¿puedes tomar decisiones basadas en señales observables? Un menor volumen de solicitudes no demuestra la migración; también debes rastrear aplicaciones activas, errores, uso de campos, migraciones completadas y la carga de soporte.
Preguntas a aclarar antes de responder
- ¿Cuál es el valor principal de v2? ¿Seguridad, rendimiento, cumplimiento normativo, costo o un nuevo modelo de recursos?
- ¿Qué comportamientos de v1 se rompen? Enumera campos eliminados, cambios de tipo, cambios de autenticación y semántica de errores.
- ¿Pueden los clientes ver lo que usan? ¿El uso está disponible por token, aplicación u organización?
- ¿Es el plazo de 12 meses una fecha límite estricta o un objetivo? ¿Qué evidencia podría justificar una extensión o un cierre escalonado?
- ¿Pueden funcionar ambas versiones o un adaptador en paralelo? ¿Cuáles son los límites de costo, latencia y consistencia?
- ¿Cuál es la promesa de soporte posterior al retiro? ¿Cómo funcionan las respuestas 410, la documentación, las apelaciones y las excepciones de seguridad?
Estructura para una respuesta de 30 segundos
«Establecería las líneas base de uso de v1 y los segmentos de clientes; luego enumeraría cada cambio incompatible y el beneficio de v2. Publicaría guías de compatibilidad, un inventario de diferencias (diff), herramientas de validación y un panel de control de uso a nivel de aplicación, comenzando con los clientes de alto valor y las integraciones internas. Durante la migración utilizaría documentación, avisos en la consola, correo electrónico y contacto directo, además de encabezados Deprecation/Sunset y simulacros de errores escalonados. Cada etapa tiene umbrales de adopción, errores, migración de aplicaciones activas y tickets de soporte; retiraría v1 solo después de cumplir con los criterios de salida, con excepciones de seguridad y una ventana breve de reversión».
Análisis detallado paso a paso
Paso 1: Definir objetivos y comportamientos que no deben romperse
Divide los objetivos en valor para el cliente y restricciones de la plataforma. Por ejemplo, v2 puede ofrecer permisos más granulares mientras la semántica central de lectura y escritura de v1 se mantiene estable durante la transición. Enumera los campos eliminados o renombrados, nuevos parámetros obligatorios, cambios de tipo y de enumeraciones (enums), y requisitos de autenticación. Una respuesta 200 por sí sola no demuestra compatibilidad.
Paso 2: Establecer líneas base de uso y niveles de riesgo
Segmenta por organización, aplicación, token, versión, endpoint, campo, volumen de solicitudes, ingresos, cumplimiento normativo y responsable técnico. Calcula la actividad a 90 días de cada aplicación, la proporción de campos afectados, la complejidad de migración y el valor del cliente. Un cliente de altos ingresos y bajo volumen aún requiere confirmación explícita; una aplicación sin responsable entra anticipadamente en la cola de riesgo.
Paso 3: Diseñar rutas de migración y límites de compatibilidad
Da preferencia a la migración aditiva: campos opcionales, respuestas paralelas o un adaptador de v1 a v2. Para campos incompatibles, proporciona mapeos equivalentes, solicitudes de ejemplo y diferencias semánticas. Asigna al adaptador una fecha límite, costo y observabilidad; no debe ocultar de forma permanente una migración incompleta por parte del cliente.
Paso 4: Convertir las herramientas y la documentación en un producto
Proporciona una lista de diferencias (diff), reportes de uso por aplicación, verificaciones estáticas o sugerencias de migración en el SDK, validación en sandbox, código de ejemplo e instrucciones de reversión. Vincula cada cambio incompatible con la sintaxis de reemplazo y un paso de prueba. El resultado de las herramientas debe ser reproducible para que los clientes no tengan que adivinar a partir de un comunicado extenso.
inventory -> classify risk -> test v2 -> dual-run -> migrate -> verify -> retire v1Paso 5: Escalonar el despliegue y la comunicación
Comienza con socios internos y de diseño, luego la migración de autoservicio y, finalmente, clientes de alto valor o complejos. Utiliza registros de cambios (changelogs), documentación para desarrolladores, banners en la consola, correos electrónicos y contacto a través de ejecutivos de cuenta en cada etapa. Consolida fecha, impacto, acción requerida, punto de contacto de soporte y términos de excepción en un único contrato de migración para que los canales no hagan promesas contradictorias.
Paso 6: Establecer compuertas basadas en señales, no solo en una tasa de adopción
Revisa semanalmente las solicitudes v1, aplicaciones activas en v1, llamadas a campos afectados, tasa de éxito en v2, tasa de reversión tras la migración, cobertura de encabezados de obsolescencia, tickets de soporte y la confirmación de clientes de alto valor. La migración está completa únicamente cuando la aplicación ha cambiado, los escenarios críticos funcionan, los errores están en niveles normales y el responsable lo ha confirmado.
Paso 7: Definir reglas de retiro, extensión y excepciones
Antes del retiro, simula un error 410 o equivalente en un entorno de prueba y verifica que los clientes vean una guía práctica. Una extensión requiere evidencia como un parche de seguridad no finalizado, un cliente regulado crítico aún en migración o una regresión confirmada en v2. Un riesgo de seguridad puede justificar un cierre anticipado, pero documentando el impacto, las alternativas y el soporte. Cada excepción debe tener una fecha de caducidad.
Paso 8: Revisar la migración e institucionalizar la gobernanza de versiones
Tras el retiro, inspecciona picos de error, retención, costo de soporte, ahorro en infraestructura y uso no previsto. Conserva los diffs entre v1/v2, las comunicaciones, los registros de decisiones y las líneas de tiempo de incidentes. Añade períodos de soporte, revisión de cambios incompatibles, encabezados de obsolescencia, pruebas de migración y notificaciones a clientes en la plantilla del siguiente lanzamiento.
Compensaciones y límites
Compensación 1: Adaptador o cambio rápido
Un adaptador reduce el riesgo a corto plazo, pero añade mantenimiento, latencia y ambigüedad semántica. Manténlo solo si el valor de la migración es claro, el límite es observable y existe una fecha de término; de lo contrario, proporciona un plazo claro para v2 en lugar de extender v1 indefinidamente.
Compensación 2: Fecha límite única o fases por clientes
Una fecha única es más fácil de operar; las fases controlan el riesgo y dan tiempo a los clientes complejos. Mantén una fecha final pública mientras estableces hitos y puntos de control basados en el riesgo para que los clientes de altos ingresos no presenten problemas en la última semana.
Compensación 3: Reducción de solicitudes o migración real de aplicaciones
Las solicitudes pueden disminuir debido a caídas en el negocio, almacenamiento en caché o desactivación. Evalúa la migración mediante aplicaciones activas, endpoints críticos exitosos, reemplazo completo de campos y confirmación del responsable, no solo mediante el tráfico total.
Simulacros de fallas y plan de evolución
Simulacro 1: Un campo incompatible omitido
Reproduce solicitudes reales muestreadas contra v2 y compara códigos de estado, objetos de error, paginación, zonas horarias y semántica de valores monetarios. Clasifica las diferencias por severidad; bloquea el tráfico más amplio ante cualquier campo crítico sin explicar.
Simulacro 2: Un cliente de alto valor sigue en v1
Genera la lista de clientes con 90 días de anticipación y verifica que la gestión de cuentas, el soporte y el equipo de producto tengan responsables asignados. Ofrece un diagnóstico técnico y una excepción de duración limitada en lugar de cortar el servicio en el último día.
Simulacro 3: Un pico de errores tras el retiro
Devuelve el error 410 con un enlace de migración en una cohorte pequeña o en sandbox. Verifica que los SDKs, la monitorización y la documentación guíen la remediación. Establece una ventana de restauración corta con activadores explícitos y registra cada activación.
Errores comunes y seguimiento
Error 1: Enviar un único correo de obsolescencia
Una notificación no reemplaza un inventario de uso, ejemplos de código, un entorno de prueba ni un punto de entrada para soporte. La migración debe ser ejecutable dentro del flujo de trabajo del cliente.
Error 2: Asumir que el número de versión cubre toda la compatibilidad
Los campos, los errores y la autenticación pueden cambiar dentro de una versión. Mantén un diff detallado y pruebas de contrato.
Error 3: Mantener la versión antigua para siempre
Un adaptador sin fecha de retiro fragmenta la documentación, sobrecarga la infraestructura y expande la superficie de seguridad. Asigna un responsable y una fecha límite a cada excepción.
Error 4: Clasificar a los clientes solo por el total de solicitudes
Aplicaciones de bajo volumen pueden ejecutar flujos contables o de cumplimiento normativo críticos. Segmenta por valor, impacto y complejidad técnica.
Error 5: Ignorar llamadas sin versión especificada
Los clientes que dependen de una versión predeterminada pueden experimentar cambios de comportamiento tras el retiro. Identifica solicitudes sin encabezado de versión y advierte durante la transición.
Error 6: No probar la reversión ni la extensión
Un ensayo en el que todo sale bien no demuestra que el riesgo esté controlado. Prueba con anticipación las guías de error, la aprobación de excepciones, las ventanas de restauración y los criterios de extensión.