Cómo construir un API Sunset Playbook para que una deprecación no se convierta en una crisis de producto la semana del apagado

Paso 1 — Mantén un inventario vivo de dependencias con fecha y owner. Cada modelo, endpoint o servicio externo recibe nombre, proveedor, versión, fecha de alta, funciones que lo consumen, criticidad y responsable interno. Añade campos para deprecationnotice, sunsetdate y alternativa conocida. No confíes en que el equipo recuerde anuncios publicados meses atrás. Una tarea automática puede revisar changelogs, pero el estado aprobado debe vivir en un registry controlado. Cuando aparece una fecha de retiro, crea trabajo con deadline anterior al sunset. El objetivo es que una deprecación entre al backlog como riesgo visible y no como sorpresa detectada por un error de producción.

Paso 2 — Escribe el exit contract antes de escoger la alternativa. Documenta qué inputs recibe la capability, qué outputs debe producir, qué metadata necesita conservar, qué datos hay que exportar y qué comportamiento mínimo exige el negocio. Separa características esenciales de extras específicos del proveedor. Este contrato funciona como criterio de migración. Si una alternativa no puede producir un requisito esencial, la decisión puede ser rediseñar la experiencia o mantener un servicio legacy durante una transición. Sin contrato, el equipo compara listas de features y puede descubrir demasiado tarde que una función aparentemente menor era necesaria para un proceso crítico.

Paso 3 — Crea un migration fixture pequeño y reproducible. Selecciona entre diez y cincuenta casos representativos con resultados verificables. Incluye inputs normales, edge cases, archivos reales sanitizados y situaciones de error. Ejecuta la integración actual y guarda baseline: calidad, latencia, costo y evidencia. Después prueba candidatos contra la misma suite. Si el servicio genera contenido creativo, usa rúbricas y revisión ciega; si produce acciones, verifica estado final. El fixture debe ser barato para poder repetirse durante el periodo de transición. La portabilidad no se demuestra por compatibilidad de API, sino por conservar outcomes suficientes sobre trabajo real.

Paso 4 — Haz un export drill antes de la fecha límite. Descarga una muestra de datos, assets, logs y metadata del proveedor y trata de reconstruir una vista útil sin depender de su interfaz. Verifica encoding, timestamps, IDs y relaciones. Si algo importante no sale, decide cómo capturarlo mientras el servicio todavía está disponible. Documenta volumen total y tiempo esperado de exportación para no descubrir que la transferencia completa requiere días. Guarda checksums cuando corresponda. El objetivo es saber que puedes salir, no asumirlo porque existe un botón de export. Un backup no probado es solo una esperanza comprimida.

Paso 5 — Introduce release gates conforme se acerca el sunset. A una distancia definida, bloquea nuevos features que aumenten dependencia salvo excepción aprobada. Después mueve tráfico de prueba a la alternativa, compara métricas y aumenta gradualmente. Si no existe reemplazo directo, activa el modo definido en el exit contract: degradar capacidad, usar otro proveedor o cerrar la función con comunicación clara. Mantén observabilidad separada para viejo y nuevo stack. Durante la última semana, el equipo debería estar confirmando estabilidad, no comenzando la investigación. Una fecha pública de sunset debe convertirse en una secuencia interna de gates más tempranos.

Paso 6 — Cierra con reconciliación y aprendizaje. Después del cambio, confirma que no quedan llamadas al endpoint retirado, que los datos exportados están accesibles y que los usuarios reciben el comportamiento esperado. Guarda un migration receipt con fechas, versión nueva, pérdidas aceptadas y métricas. Actualiza dependencydebt y time-to-exit real para futuras decisiones. En Goatify, este playbook puede automatizarse como parte del catálogo de habilidades: cada skill externa declara fecha de revisión y un test de sustitución. El objetivo no es vivir migrando; es convertir un evento inevitable del ecosistema en mantenimiento controlado en vez de una emergencia que paraliza producto y soporte.