Plan de Deprecación — TaskFlow API v1 → v2

Diagnóstico del sistema legacy

Endpoints activos

18/47

29 sin uso en 90 días

Consumidores externos

340

integraciones cliente

SDK v1 descargas

1.2k

por mes (npm)

API v2 en prod.

8m

estable y probada

Marco de decisión

Preguntas de evaluación

1
¿Proporciona valor único la API v1? Los 18 endpoints activos tienen equivalente completo en v2
NO
2
¿Cuántos consumidores dependen de ella? 340 ext. + 2 microservicios internos + SDK + admin panel
ALTO
3
¿Existe reemplazo en producción? API v2 GraphQL + JWT lleva 8 meses estable en producción
SÍ
4
¿Coste de migración por consumidor? SDK: automatizable. Integraciones externas: requiere guía + herramienta
MEDIO
5
¿Coste de NO deprecar? Vulnerabilidad auth (API key en querystring), deuda técnica creciente
ALTO

Riesgos del sistema legacy

!
Vulnerabilidad de seguridad crítica API key expuesta en URL → logs, historial de browser, proxies
CRÍTICO
!
Bugs con "comportamiento dependido" 3 bugs documentados con workarounds; usuarios se bloquean al arreglarlos
ALTO
!
Sin paginación estándar Timeouts en cuentas >500 tareas; solucionado en v2
MEDIO
!
Coste doble de mantenimiento 2 superficies de API = 2x tests, 2x docs, 2x actualizaciones de seguridad
MEDIO
→
Zombie endpoints (29 sin uso) Superficie de ataque innecesaria, coste de mantenimiento cero retorno
BAJO

⚠️

Decisión: RETIRAR — Deprecación Compulsory

La vulnerabilidad de seguridad (API key en querystring) justifica una deprecación compulsiva con fecha límite. No es viable mantener indefinidamente ambas versiones. Se proporcionará tooling de migración automática, guía detallada y soporte activo durante el proceso. Fecha de desconexión: 31 de marzo 2027.

Tipo	Cuándo usar	Mecanismo	Selección
Advisory	Sistema estable, migración opcional, sin urgencia de seguridad	Avisos, documentación, recordatorios. Usuarios migran a su ritmo.	—
Compulsory	Riesgo de seguridad, mantenimiento insostenible o bloquea roadmap	Deadline duro (31-03-2027). Tooling de migración automática. Soporte activo.	✓ ELEGIDO

Consumidores y estrategia de migración

Integraciones externas (Zapier, custom)

Externo

Consumidores ~340 clientes

Esfuerzo/consumidor Bajo-Medio

Patrón Strangler

Responsable Cliente (con guía)

notification-service + report-service

Interno

Consumidores 2 microservicios

Esfuerzo/consumidor Alto

Patrón Adapter

Responsable Equipo ingeniería

@taskflow/sdk-v1 (npm)

SDK

Consumidores 1.200 desc/mes

Esfuerzo Automatizable

Patrón Feature Flags

Acción Lanzar @taskflow/sdk-v2

Panel de administración interno

Admin

Endpoints usados 6 de 18 activos

Esfuerzo Bajo

Patrón Strangler

Prioridad Sprint 1 (rápido)

Fases de migración · Junio 2026 – Marzo 2027

1

Preparación

Jun – Jul 2026

Tooling, anuncio oficial, documentación de migración

2

Migración interna

Jul – Ago 2026

Admin panel + notification + report service

3

SDK v2 + clientes

Sep – Nov 2026

Lanzamiento @taskflow/sdk-v2. Migración guiada de clientes

4

Throttle gradual

Dic 2026 – Feb 2027

Rate limiting v1, métricas de adopción, soporte final

5

Eliminación

31 Mar 2027

Apagado API v1. Eliminación de código, tests y docs.

Fase 1 — Preparación y anuncio

Jun – Jul 2026

Medir usage actual: instrumentar logs para verificar qué endpoints usa cada cliente
Script de migración automática: npx @taskflow/migrate-v1-v2 — reemplaza imports, adapta auth
Migration guide pública: docs.taskflow.io/migrate-v1-to-v2 con ejemplos antes/después
Email a todos los clientes con integraciones activas: anuncio oficial con fecha límite 31-03-2027
Deprecation header en todas las respuestas v1: Deprecation: true; Sunset: Wed, 31 Mar 2027

Fase 2 — Migración de consumidores internos

Jul – Ago 2026

Admin panel (6 endpoints): migrar a v2 GraphQL, tests de regresión — estimado 3 días
notification-service: patrón Adapter — crear LegacyNotificationAdapter → delega a v2; migrar progresivamente
report-service: mayor complejidad (queries anidadas); migrar con Feature Flag para rollback seguro
Zero-usage verification: confirmar 0 llamadas v1 desde servicios internos antes de pasar a Fase 3

Fase 3 — SDK v2 y migración de clientes

Sep – Nov 2026

Publicar @taskflow/sdk-v2 con compatibilidad GraphQL, webhooks y JWT auth
Marcar @taskflow/sdk-v1 como deprecated en npm con mensaje apuntando a v2
Office hours semanales: sesiones de soporte para clientes con integraciones complejas (Zapier, custom)
Dashboard de progreso para clientes: cada cliente puede ver si sus integraciones están ya en v2
Incentivo: 1 mes gratis para clientes que migren antes del 30-nov-2026

Fase 4 — Throttle gradual y soporte final

Dic 2026 – Feb 2027

Rate limit progresivo en v1: 100 rpm (dic) → 50 rpm (ene) → 10 rpm (feb) para presionar migración
Email semanal a clientes aún en v1 con contador de días restantes
Identificar stragglers: contacto directo a los últimos 20 clientes que no han migrado
Freeze de código v1: no se aplican parches ni mejoras; solo mantenimiento de seguridad crítico

Fase 5 — Eliminación definitiva

31 Mar 2027

Verificar 0 llamadas activas a v1 en las últimas 72h (métricas + logs)
Desconectar endpoints v1 del load balancer — retornar 410 Gone con mensaje de migración
Eliminar código: routes, controllers, schemas v1, tests asociados, middleware específico
Eliminar documentación legacy y redirigir URLs antiguas a docs v2
Remover deprecation notices del código v2 (ya cumplieron su función)
Celebrar: código eliminado = deuda técnica reducida = equipo más ágil

Patrones de migración aplicados

🔀

Strangler Pattern

Aplicado en: Admin Panel Integraciones ext.

Enrutar tráfico progresivamente de v1 a v2. Cuando v1 tiene 0% de tráfico, se elimina. Sin big bang, sin downtime.

            nginx.conf — Traffic split
            nginx
          
# Fase 3: 50% tráfico a v2
upstream api_v1 {
  server v1:3000 weight=50;
}
upstream api_v2 {
  server v2:4000 weight=50;
}
# Fase 5: 0% a v1 → eliminar

🔌

Adapter Pattern

Aplicado en: notification-service report-service

Implementar la interfaz legacy delegando a la implementación nueva. Los microservicios no cambian su código mientras el backend migra.

            legacy-task-adapter.ts
            TypeScript
          
class LegacyTaskAdapter implements OldTaskAPI {
  constructor(private v2: TaskServiceV2) {}

  getTask(id: number): OldTask {
    const task = this.v2.findById(String(id));
    return this.toOldFormat(task);
  }
}

🚩

Feature Flag Migration

Aplicado en: SDK report-service

Controlar qué consumidores usan v2 uno a uno. Permite rollback instantáneo si se detectan problemas. Migración sin riesgo.

            task-service.factory.ts
            TypeScript
          
function getTaskService(
  clientId: string
): TaskService {
  if (flags.isOn('api-v2', { clientId })) {
    return new TaskServiceV2();
  }
  return new LegacyTaskService();
}

Progresión de tráfico — Strangler Pattern (proyección)

Jun '26

Sep '26

Nov '26

Feb '27

Mar '27

API v1 (legacy)

API v2 (nueva)

Checklist de verificación — antes de eliminar

v2 está en producción y cubre todos los casos críticos de v1

Migration guide publicada con ejemplos antes/después

Script npx @taskflow/migrate-v1-v2 disponible y testeado

Todos los consumidores internos migrados (0 llamadas v1)

SDK v2 publicado; SDK v1 marcado deprecated en npm

0 llamadas activas a v1 en las últimas 72h (métricas)

Código v1 eliminado (routes, controllers, schemas, tests, docs)

Deprecation notices removidos del código base

URLs legacy redirigen a docs v2 (301 redirect)

Retrospectiva post-migración documentada (lecciones aprendidas)

Racionalizaciones peligrosas — cómo detectarlas

⚠️ Mentiras comunes vs. realidad del proyecto

✗ "La API v1 todavía funciona, ¿para qué cambiarla?"

✓ La autenticación via querystring es una vulnerabilidad activa. El coste de seguridad crece cada mes.

✗ "Algunos clientes migrarán solos cuando quieran"

✓ No lo harán. La inercia es enorme. Debes proporcionar tooling, incentivos y presión gradual (Churn Rule).

✗ "Podemos mantener v1 y v2 indefinidamente"

✓ Doble coste de tests, seguridad, docs, onboarding. En 18 meses eso es equivalente a 2 ingenieros a tiempo completo.

✗ "Los 29 endpoints sin uso no hacen daño"

✓ Son superficie de ataque, aumentan el tiempo de auditoría y confunden a nuevos ingenieros.

✗ "Anunciar el deadline es suficiente"

✓ Sin tooling, guía y soporte activo, el deadline crea caos. Proporciona el camino, no solo la fecha.

Deprecación API v1 → v2