Versionado y deprecación de APIs: gobernar el contrato en producción

El contrato de una API no termina cuando la integración pasa a producción. Ahí empieza su etapa más costosa: convive con consumidores que dependen de campos, códigos de error y formatos que ya no controlas del todo. Cuando ese contrato no se gobierna, cada cambio se transforma en una negociación informal por correo, en un despliegue coordinado a última hora o en un incidente que nadie anticipó.

Este artículo aborda el gobierno del contrato una vez publicada la API: cómo versionar, cómo deprecar y cómo sostener la trazabilidad de los cambios sin romper integraciones que ya están operando. Asume que la decisión de conectar sistemas ya ocurrió y que el desafío actual es mantener el contrato bajo control.

Por qué el contrato publicado se degrada sin gobierno

Un contrato de API es un acuerdo técnico entre un proveedor y uno o más consumidores. En entornos empresariales esos consumidores rara vez son uno: un ERP, un portal de clientes, un servicio de facturación electrónica, una integración con un proveedor logístico. Cada uno interpretó el contrato a su manera y fijó supuestos que no están escritos en ninguna parte.

La degradación ocurre por acumulación:

• Campos agregados sin documentar que algún consumidor empieza a usar como si fueran estables.
• Códigos de error nuevos que los consumidores no reconocen y tratan como fallo genérico.
• Cambios de comportamiento en validaciones que antes aceptaban un valor y ahora lo rechazan.
• Timeouts y límites de tasa ajustados sin aviso, que rompen procesos batch nocturnos.

Ninguno de estos cambios es necesariamente un error de diseño. El problema es que se aplican sin un mecanismo que permita al consumidor anticiparlos, detectarlos y adaptarse. Sin gobierno, el contrato se convierte en un documento histórico que ya no refleja lo que el sistema hace.

Versionado: qué cambia y cómo se comunica

Versionar no es solo agregar /v2 a la ruta. Es clasificar cada cambio según su impacto sobre los consumidores existentes y decidir qué mecanismo de comunicación exige.

Cambios compatibles

Son aquellos que un consumidor bien construido puede ignorar sin romperse:

• Agregar campos opcionales en la respuesta.
• Agregar parámetros opcionales en la solicitud.
• Agregar nuevos códigos de error que el consumidor puede tratar como caso no contemplado.
• Ampliar la documentación sin alterar comportamiento.

Estos cambios no requieren nueva versión mayor, pero sí registro y comunicación. Un consumidor que no sabe que existe un campo nuevo no puede aprovecharlo, y uno que recibe un código de error desconocido puede fallar de forma silenciosa si su manejo de errores es pobre.

Cambios incompatibles

Son los que rompen supuestos existentes:

• Eliminar o renombrar un campo.
• Cambiar el tipo de dato de un campo.
• Volver obligatorio un parámetro que antes era opcional.
• Alterar la semántica de un código de error existente.
• Cambiar el formato de fechas, montos o identificadores.

Estos cambios exigen una nueva versión mayor y un período de coexistencia. La versión anterior debe seguir operando mientras los consumidores migran, y ese período debe estar definido antes de publicar la nueva, no después.

El error frecuente: versionar por comodidad

Un patrón común es crear una versión nueva para cada cambio, incluso los compatibles. El resultado es una proliferación de versiones que nadie mantiene, consumidores en versiones antiguas sin plan de migración y un equipo que dedica más tiempo a sostener versiones muertas que a evolucionar el servicio.

El criterio práctico: versiona cuando el cambio rompe, no cuando el cambio agrega. Y cuando versiones, define explícitamente cuánto tiempo vivirá la versión anterior y qué condiciones debe cumplir un consumidor para quedarse en ella.

Deprecación: el proceso que casi nadie documenta

Deprecar no es apagar. Es un proceso con etapas, plazos y evidencia. Sin ese proceso, la deprecación se convierte en una fecha arbitraria que el equipo de operaciones descubre cuando algo deja de funcionar.

Un proceso de deprecación sostenible tiene al menos cuatro elementos:

1. Anuncio formal con fecha de corte. No basta con un correo; el aviso debe quedar en el canal que el consumidor efectivamente monitorea (changelog, portal de desarrolladores, ticket de integración).
2. Período de coexistencia. La versión antigua y la nueva operan en paralelo durante un plazo definido, proporcional a la criticidad del consumidor y no al calendario del equipo proveedor.
3. Instrumentación de uso. Necesitas saber qué consumidores siguen llamando a la versión antigua, con qué frecuencia y desde qué identificador. Sin esa medición, la deprecación es a ciegas.
4. Criterio de corte. Qué ocurre cuando llega la fecha: ¿se devuelve un error explícito de versión obsoleta? ¿Se redirige? ¿Se mantiene un modo degradado? La decisión debe estar tomada antes, no el día del corte.

El punto crítico es el tercero. La instrumentación de uso separa una deprecación gobernada de una apuesta. Si no puedes responder "quién sigue usando la v1 y para qué", no estás en condiciones de deprecarla.

Trazabilidad del cambio: qué registrar y para qué

La trazabilidad en esta etapa no es la del request individual, sino la del cambio sobre el contrato. Necesitas poder reconstruir qué cambió, cuándo, por qué y a quién afectó.

Un registro mínimo de cambios de contrato debería capturar:

• Identificador del cambio y versión afectada.
• Clasificación: compatible o incompatible.
• Descripción técnica del cambio (campo, endpoint, código de error).
• Consumidores identificados como afectados.
• Fecha de anuncio y fecha de corte si aplica.
• Evidencia de migración o de aceptación del consumidor.

Este registro cumple tres funciones operativas:

• Resolver incidentes: cuando un consumidor reporta un fallo, el registro permite correlacionarlo con un cambio reciente.
• Sostener auditorías: en contextos donde la operación debe demostrar control sobre sus integraciones, el registro es evidencia de gobierno, no una garantía de cumplimiento normativo.
• Alimentar la deprecación: sin registro, no hay forma de saber qué versiones están vivas ni quién las usa.

La trazabilidad del cambio se complementa con la trazabilidad de la llamada: un identificador de correlación que permita seguir una transacción a través de los sistemas integrados. Pero esa es una decisión de observabilidad en producción, distinta del gobierno del contrato. Ambas se necesitan; confundirlas lleva a instrumentar requests sin gobernar cambios.

Señales de que el contrato ya está fuera de control

Antes de invertir en un proceso formal, conviene reconocer los síntomas. Estas señales indican que el gobierno del contrato ya es una deuda operativa:

• Nadie sabe cuántas versiones están activas ni cuántos consumidores usan cada una.
• Los cambios se comunican por canales informales y dependen de que alguien recuerde avisar.
• Los consumidores descubren los cambios en producción, no en un changelog.
• La documentación no coincide con el comportamiento real del endpoint.
• Deprecar una versión requiere coordinación manual con cada consumidor.
• Los incidentes de integración se investigan sin registro de cambios y se atribuyen a "fallas del otro sistema".

Si reconoces dos o más de estas señales, el problema no es técnico sino de gobierno. La solución no es reescribir la API, sino establecer el proceso que hoy no existe.

Criterio práctico para ordenar el contrato en operación

Ordenar el gobierno del contrato no requiere un proyecto de meses. Requiere decisiones explícitas y disciplina sostenida:

1. Inventaria versiones y consumidores. Antes de cualquier cambio, necesitas saber qué está vivo. La instrumentación de uso es el primer paso, no el último.
2. Define la política de versionado. Qué se considera compatible, qué incompatible y qué mecanismo se usa para cada caso. Escríbela y publícala.
3. Establece el proceso de deprecación. Plazos, canales de aviso, criterios de corte y qué ocurre con quien no migra.
4. Mantén un registro de cambios de contrato. Con los campos mínimos descritos arriba, actualizado en cada despliegue que altere el contrato.
5. Revisa el proceso periódicamente. Un gobierno que no se audita se degrada igual que el contrato que pretendía controlar.

Este trabajo se apoya en el mismo equipo que sostiene el Desarrollo de Software de la organización, pero su foco no es construir la API: es sostener el acuerdo que la API representa a lo largo del tiempo.

El contrato como activo operativo

Una API empresarial publicada es un contrato vivo. Versionarlo, deprecarlo y trazarlo no son tareas de documentación: son decisiones de arquitectura operativa que determinan si las integraciones resisten el cambio o colapsan con él. La diferencia entre una integración frágil y una gobernada no está en el diseño inicial, sino en lo que ocurre después de la primera versión en producción.

Si tu operación ya tiene integraciones activas y no puedes responder con precisión qué versiones están vivas, quién las consume y qué cambió en el último trimestre, ese es el punto de partida. Conversemos sobre cómo evaluar el gobierno de tus integraciones y qué priorizar en tu contexto.