APIs: cómo retirar versiones sin romper integraciones

Publicar una versión nueva no retira la antigua#

Los clientes pueden seguir usando una versión de API mucho después de que el equipo publique su sucesora. Una retirada fiable necesita saber quién consume cada ruta, qué cambio debe realizar, cómo probarlo y qué evidencia permite decidir que el servicio anterior puede dejar de responder.

La RFC 9745 define la cabecera HTTP Deprecation: comunica el estado de obsolescencia, pero no cambia por sí misma el comportamiento del recurso. La RFC 8594 define Sunset para anunciar cuándo se espera que un recurso deje de estar disponible. Ninguna de las dos sustituye la comunicación directa ni obliga a un cliente a migrar automáticamente.

Secuencia de retirada#

1. Inventariar: asocia credenciales o clientes con equipos responsables, rutas, versión y frecuencia de uso. Si hay consumidores desconocidos, reduce esa incertidumbre antes de fijar el corte.
2. Preparar el reemplazo: documenta cambios incompatibles, ejemplos, límites, autenticación, errores y pasos de migración. Ofrece un entorno de prueba y pruebas de contrato.
3. Anunciar: informa a consumidores y responsables internos con motivo, alternativa, calendario, canal de soporte y consecuencias previstas. Registra excepciones y propietario.
4. Señalizar: usa Deprecation y enlaces a documentación cuando encaje con la infraestructura. Si la fecha de retirada está confirmada, considera Sunset; verifica que proxies y gateways preservan las cabeceras.
5. Medir: observa llamadas por versión, fallos, consumidores sin identificar y solicitudes de ayuda. Envía avisos a dueños conocidos antes de aumentar la presión de migración.
6. Retirar y comprobar: aplica el cambio aprobado, monitoriza errores y mantiene un procedimiento de escalado acorde con los contratos y el riesgo.

Condición de salida#

No retires una versión solo porque el nuevo endpoint exista. Define una condición verificable: consumidores críticos migrados o excepción aprobada, periodo anunciado cumplido, soporte preparado, pruebas de regresión aprobadas y plan de reversión o mitigación entendido.

Enlaza esta guía con el diseño contract-first de API con OpenAPI y la idempotencia en APIs y webhooks. Para servicios externos, coordina el calendario con los equipos consumidores y revisa las obligaciones de disponibilidad y notificación pactadas.