Sunset de API

Definition

¿Alguna vez has usado una app o servicio que de repente dejó de funcionar, sin ningún aviso? Esa experiencia frustrante es exactamente lo que los procesos de sunset de API están diseñados para prevenir. Un “sunset” es el retiro planificado, comunicado y ordenado de una API - la etapa final en el ciclo de vida de una API donde transiciona de deprecada a completamente no disponible.

Mientras que la deprecación es el anuncio de que algo eventualmente desaparecerá (como un cartel de “cerramos el negocio”), el sunset es el cierre real. El proceso de sunset incluye establecer una fecha de fin firme, comunicar esa fecha a través de múltiples canales (incluyendo el header HTTP Sunset estandarizado definido en RFC 8594), proporcionar rutas de migración a APIs de reemplazo, y finalmente, cerrar el endpoint permanentemente. Un sunset bien ejecutado da a los desarrolladores meses o incluso años de aviso, alternativas claras, y soporte durante la transición - asegurando que cuando las luces finalmente se apaguen, nadie quede en la oscuridad.

La importancia de procedimientos apropiados de sunset no puede subestimarse. Las APIs frecuentemente potencian procesos de negocio críticos, aplicaciones móviles e integraciones de las que las empresas dependen diariamente. Un cierre repentino de API puede causar caídas en producción, pérdida de ingresos y destruir la confianza. Empresas como Google, Microsoft y Stripe han aprendido esto por experiencia y ahora mantienen políticas públicas de ciclo de vida de API que especifican períodos mínimos de aviso (frecuentemente 12-24 meses) y protocolos claros de comunicación. El header Sunset se ha convertido en el estándar de la industria para fechas de retiro legibles por máquina, permitiendo que herramientas automatizadas adviertan a los desarrolladores antes de que sea demasiado tarde.

Example

Política de Sunset de 12 Meses de Google: Cuando Google decide hacer sunset de una API, siguen un proceso riguroso. Por ejemplo, cuando Google deprecó la API de Google+, lo anunciaron en octubre de 2018 con una fecha de sunset de marzo de 2019 - dando a los desarrolladores 5 meses para migrar. Para APIs más establecidas, Google garantiza al menos 12 meses de aviso. Durante este período, las respuestas de API incluyen headers Sunset y Deprecation, la consola de desarrollador muestra advertencias prominentes, y se publican guías de migración. Después de la fecha de sunset, las solicitudes devuelven 410 Gone con un mensaje de error útil apuntando a alternativas.

Enfoque de Sunset Gradual de Stripe: Stripe usa versiones de API basadas en fechas (como 2024-11-20). Cuando hacen sunset de versiones antiguas, comienzan con notificaciones por email 18+ meses antes de la fecha de sunset. A medida que la fecha se acerca, agregan advertencias de deprecación a las respuestas de API, destacan los endpoints afectados en el dashboard, y proporcionan guías de migración detalladas. Los desarrolladores pueden probar su código contra la nueva versión en modo test antes del sunset. El día del sunset, las versiones antiguas dejan de funcionar, pero el enfoque de Stripe significa que la mayoría de los desarrolladores ya han migrado.

Sunset de Twitter API v1 (El Ejemplo Controversial): El sunset de la API v1 de Twitter en 2013 es frecuentemente citado como una historia de advertencia. A pesar de proporcionar un período de migración, muchos desarrolladores se sintieron sorprendidos por los cambios en v1.1 (especialmente los cambios en límites de tasa y requisitos de autenticación). El sunset rompió miles de apps de terceros. Esta experiencia enseñó a la industria que el éxito del sunset depende no solo del cronograma, sino de proporcionar funcionalidad verdaderamente equivalente en la API de reemplazo.

Sunset de Versiones de Facebook Graph API: Facebook mantiene un ciclo de vida de 2 años para cada versión de Graph API. Cuando estás usando la versión 16.0 y se lanza la versión 18.0, la versión 16.0 entra en su cuenta regresiva de 2 años hacia el sunset. El proceso es altamente predecible: se envían emails automatizados, el Dashboard de Desarrolladores muestra advertencias, y el header Sunset aparece en las respuestas. Esta cadencia predecible permite a las empresas planificar sus sprints de migración años por adelantado.

Proceso de Retiro de Twilio: Cuando Twilio hizo sunset de su arquitectura original de Programmable Voice, proporcionaron una ventana de migración de varios años. Crearon un sitio web dedicado como hub de migración, ofrecieron consultas de migración gratuitas para clientes grandes, realizaron webinars explicando los cambios, e incluso proporcionaron extensiones temporales para desarrolladores que no podían cumplir con la fecha límite original. El header sunset estuvo presente en cada respuesta de API durante meses antes del cierre.

Analogy

La Venta de Cierre de Tienda: Imagina una tienda que anuncia que está cerrando. Primero, hay carteles de “cerramos el negocio” (anuncio de deprecación). Luego se publican fechas específicas de cierre (header Sunset). Durante el período de cierre, ayudan a los clientes a encontrar tiendas alternativas para sus necesidades (guías de migración). Los clientes regulares reciben notificaciones personales (emails a desarrolladores). El último día, las puertas se cierran definitivamente (410 Gone). Un cierre de tienda bien ejecutado da a los clientes tiempo para encontrar alternativas; un cierre repentino deja a todos luchando.

La Discontinuación de Ruta Aérea: Cuando una aerolínea decide dejar de volar una ruta, no simplemente cancelan los vuelos de mañana. Anuncian la fecha del último vuelo meses por adelantado, dejan de vender boletos para fechas después de esa, ayudan a los pasajeros a reservar en aerolíneas asociadas, ofrecen créditos o alternativas, y gradualmente reducen operaciones. El proceso de sunset para APIs replica esto - una reducción ordenada con comunicación clara y alternativas.

El Final de Serie de TV: Cuando una serie de TV amada termina, las cadenas no simplemente dejan de transmitir a mitad de temporada. Anuncian que es la temporada final, dan tiempo a los escritores para cerrar las tramas, promocionan el final de la serie, y frecuentemente proporcionan contenido detrás de cámaras sobre el final. Los espectadores obtienen cierre. Los sunsets de API deberían proporcionar la misma experiencia - aviso anticipado, funcionalidad cerrada y conclusión clara.

El Fin de Vida del Software: Piensa en cómo Microsoft manejó el fin de vida de Windows 7. Anunciaron la fecha años por adelantado, proporcionaron rutas de actualización a Windows 10, extendieron actualizaciones de seguridad para aquellos que necesitaban más tiempo, e hicieron la fecha extremadamente prominente a medida que se acercaba. Incluso después de la fecha de sunset, el software todavía “funcionaba” - solo dejó de recibir actualizaciones. Algunas APIs similarmente transicionan a “no soportada pero funcional” antes del cierre completo.

Diagram

sequenceDiagram
    participant Dev as Desarrollador
    participant API as Endpoint API
    participant Email as Email/Dashboard

    Note over API: Fase Activa (Sin sunset planificado)
    Dev->>API: GET /v1/users
    API-->>Dev: 200 OK (respuesta normal)

    Note over Email: Sunset Anunciado (12 meses antes)
    Email-->>Dev: "sunset de v1 programado para 2025-12-31"

    Note over API: Fase Deprecación (Header Sunset agregado)
    Dev->>API: GET /v1/users
    API-->>Dev: 200 OK + Sunset: Sat, 31 Dec 2025 23:59:59 GMT

    Note over Email: Recordatorio (6 meses antes)
    Email-->>Dev: "sunset de v1 en 6 meses - migrar a v2"

    Note over Email: Advertencia (1 mes antes)
    Email-->>Dev: "URGENTE: sunset de v1 en 30 días"

    Note over API: Aviso Final (1 semana antes)
    Dev->>API: GET /v1/users
    API-->>Dev: 200 OK + Header Sunset + Warning: "7 días restantes"

    Note over API: Fecha de Sunset Alcanzada
    Dev->>API: GET /v1/users
    API-->>Dev: 410 Gone + Link de migración

Code Example

# Respuesta de API ANTES del Anuncio de Sunset
# Operación normal, sin headers de ciclo de vida

GET /v1/products HTTP/1.1
Host: api.company.com

HTTP/1.1 200 OK
Content-Type: application/json

{"products": [...]}

# ──────────────────────────────────────────────────

# Respuesta de API DESPUÉS del Anuncio de Sunset (RFC 8594)
# Headers de Deprecation y Sunset agregados

GET /v1/products HTTP/1.1
Host: api.company.com

HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: true
Sunset: Sat, 31 Dec 2025 23:59:59 GMT
Link: <https://api.company.com/v2/products>; rel="successor-version"
Link: <https://docs.company.com/migration/v1-to-v2>; rel="deprecation"
Warning: 299 - "API v1 está deprecada. Migrar a v2 antes del 2025-12-31"

{
  "products": [...],
  "_deprecation_notice": {
    "message": "Esta versión de API tendrá sunset el 2025-12-31",
    "migration_guide": "https://docs.company.com/migration/v1-to-v2",
    "successor_endpoint": "https://api.company.com/v2/products",
    "days_remaining": 180
  }
}

# ──────────────────────────────────────────────────

# Respuesta de API DESPUÉS de la Fecha de Sunset
# Endpoint retorna 410 Gone con error útil

GET /v1/products HTTP/1.1
Host: api.company.com

HTTP/1.1 410 Gone
Content-Type: application/problem+json
Link: <https://api.company.com/v2/products>; rel="successor-version"

{
  "type": "https://api.company.com/errors/sunset",
  "title": "Sunset de Versión de API",
  "status": 410,
  "detail": "API v1 fue retirada permanentemente el 2025-12-31. Por favor migrar a v2.",
  "instance": "/v1/products",
  "sunset_date": "2025-12-31T23:59:59Z",
  "successor": {
    "endpoint": "https://api.company.com/v2/products",
    "documentation": "https://docs.company.com/v2",
    "migration_guide": "https://docs.company.com/migration/v1-to-v2"
  },
  "support_contact": "[email protected]"
}

# ──────────────────────────────────────────────────

# Ejemplo: Header Sunset con Link Relations (RFC 8594 + RFC 8288)

HTTP/1.1 200 OK
Deprecation: @1640995200
Sunset: Wed, 01 Jan 2025 00:00:00 GMT
Link: <https://api.example.com/docs/sunset>; rel="sunset"
Link: <https://api.example.com/v2/resource>; rel="successor-version"
Link: <https://api.example.com/deprecation-policy>; rel="deprecation"

# ──────────────────────────────────────────────────

# Ejemplo de Implementación de Cronograma de Sunset (JSON)

{
  "api_sunset_timeline": {
    "endpoint": "/v1/products",
    "timeline": [
      {
        "phase": "announcement",
        "date": "2024-06-01",
        "action": "Publicar aviso de sunset, agregar header Deprecation",
        "headers_added": ["Deprecation: true"]
      },
      {
        "phase": "sunset_header",
        "date": "2024-07-01",
        "action": "Agregar header Sunset con fecha específica",
        "headers_added": ["Sunset: Wed, 01 Jan 2025 00:00:00 GMT"]
      },
      {
        "phase": "email_campaign",
        "date": "2024-09-01",
        "action": "Enviar email a todos los desarrolladores usando este endpoint"
      },
      {
        "phase": "warning_responses",
        "date": "2024-11-01",
        "action": "Agregar mensajes de advertencia al cuerpo de respuesta"
      },
      {
        "phase": "final_notice",
        "date": "2024-12-15",
        "action": "Último email masivo, advertencias prominentes en dashboard"
      },
      {
        "phase": "sunset",
        "date": "2025-01-01",
        "action": "Retornar 410 Gone, endpoint completamente retirado"
      }
    ]
  }
}

Security Notes

Best Practices

1. Anuncia fechas de sunset con al menos 12 meses de anticipación - Las APIs principales deberían dar a los desarrolladores un año o más para migrar. Incluso endpoints menores merecen 3-6 meses de aviso.

2. Usa el header HTTP Sunset (RFC 8594) - Las fechas de sunset legibles por máquina permiten que herramientas de desarrolladores, SDKs y sistemas de monitoreo detecten y adviertan automáticamente sobre retiros próximos.

3. Proporciona una ruta de migración completa - No solo anuncies el sunset; proporciona documentación, ejemplos de código, e idealmente herramientas de migración automatizadas para la API sucesora.

4. Comunica a través de múltiples canales - No dependas solo de headers HTTP. Usa email, dashboards de desarrolladores, posts de blog, redes sociales y eventos presenciales para alcanzar a todos los desarrolladores afectados.

5. Incluye información de deprecación en los cuerpos de respuesta - Algunos desarrolladores no revisan los headers. Agregar un campo _deprecation a las respuestas JSON (manteniendo compatibilidad del esquema) asegura visibilidad.

6. Ofrece soporte de migración - Para sunsets mayores, considera soporte dedicado de migración, horarios de oficina, o incluso servicios profesionales para ayudar a clientes grandes en la transición.

7. Implementa degradación elegante después del sunset - En lugar de errores 500 inmediatos, retorna 410 Gone con mensajes de error útiles apuntando a alternativas.

8. Rastrea y contacta usuarios activos - Identifica desarrolladores que todavía usan activamente endpoints a medida que el sunset se acerca y comunícate directamente con asistencia de migración.

9. Considera políticas de extensión - Ten un proceso para otorgar extensiones de fecha límite a desarrolladores con desafíos legítimos de migración.

10. Documenta el sunset públicamente - Mantén un changelog público o cronograma de deprecación que los desarrolladores puedan referenciar y compartir con sus stakeholders.

Common Mistakes

Período de aviso insuficiente - Dar a los desarrolladores solo semanas para migrar de APIs sobre las que han construido negocios destruye la confianza y causa incidentes en producción. Mínimo 6 meses para cambios menores, 12+ meses para APIs principales.

Sunset silencioso - Cerrar APIs sin el header Sunset o cualquier comunicación deja a los desarrolladores con aplicaciones rotas y sin explicación.

Sin API sucesora - Hacer sunset de una API sin proporcionar una alternativa deja a los desarrolladores varados. Si la funcionalidad se está eliminando completamente, sé explícito sobre eso.

Fechas de sunset inconsistentes - Anunciar una fecha en emails, una fecha diferente en headers, y realmente hacer sunset en una tercera fecha causa confusión y confianza rota.

Breaking changes disfrazados de sunset - A veces lo que se etiqueta como “sunset” es realmente un breaking change al mismo endpoint. Sé claro sobre si los desarrolladores necesitan migrar a una nueva URL o solo actualizar su código.

Ignorar la cola larga - Algunos desarrolladores se pierden todas las comunicaciones. El endpoint debería retornar respuestas 410 útiles indefinidamente después del sunset, no errores misteriosos.

Sin período de gracia - Cortar el acceso exactamente a medianoche en la fecha de sunset atrapa a desarrolladores confundidos con zonas horarias. Considera un período de gracia de 24-48 horas con respuestas de advertencia.

Olvidar los SDKs - Si proporcionas SDKs, también necesitan actualizaciones. No hagas sunset de una API mientras tu SDK oficial todavía hace llamadas a ella por defecto.

Standards & RFCs

Related Terms