Integraciones B2B: cómo gestionar el versionado de una API de datos sin romper el pipeline
Integraciones B2B: cómo gestionar el versionado de una API de datos sin romper el pipeline
El proveedor envía un correo a las 17:00 del viernes. "Publicamos la v2 de la API el próximo lunes". Sin más. Sin changelog detallado. Sin periodo de solapamiento garantizado. El equipo técnico tiene 72 horas para decidir si migra, si mantiene la v1 mientras sea posible o si acepta el riesgo de que ambas versiones coexistan en producción con comportamientos distintos.
Esta situación no es excepcional. En integraciones B2B que dependen de APIs de datos externas —señales de medios, tendencias, menciones, datos derivados del universo público— el versionado es uno de los vectores de riesgo más infravalorados. Se habla mucho de disponibilidad y latencia. Casi nadie habla de qué pasa cuando el contrato de la API cambia.
La causa habitual no es mala voluntad del proveedor. Es que el ciclo de vida de una API de datos evoluciona más rápido de lo que el equipo integrador puede absorber. Si el pipeline no está diseñado para encajar esa fricción, cada versión nueva se convierte en una deuda técnica acumulada.
Por qué el versionado de APIs de datos es diferente al versionado de APIs transaccionales
En una API transaccional —pago, autenticación, CRM— el contrato es relativamente estable. Los campos cambian poco porque el modelo de negocio subyacente cambia poco.
En una API de datos, especialmente de media intelligence o Text and Data Mining, el modelo de datos es la superficie de cambio principal. El proveedor añade campos de enriquecimiento, cambia la taxonomía de categorías, introduce nuevos niveles de análisis de sentimiento, depreca identificadores de fuente. Cada uno de esos cambios puede ser semánticamente compatible pero estructuralmente disruptivo.
El problema concreto: tu pipeline puede seguir recibiendo respuestas HTTP 200 mientras parsea datos que ya no significan lo mismo. No hay error. Solo hay ruido que contamina el análisis aguas abajo.
Estrategia 1: contrato explícito de versión en cada llamada
El primer nivel de defensa es que la versión de la API forme parte del contrato de cada llamada, no solo de la URL base.
GET /v2/mentions?q=energia+renovable&version=2024-09 HTTP/1.1
Accept: application/json
X-API-Version: 2024-09
El header X-API-Version o el parámetro version te permite anclar el comportamiento esperado incluso si el proveedor publica cambios menores dentro de la misma versión mayor. Muchos equipos omiten esto porque la URL ya incluye v2. Error: la versión en la URL controla la interfaz mayor; la versión de fecha controla el comportamiento semántico dentro de esa interfaz.
Revisa si tu proveedor soporta este nivel de anclaje. Si no lo soporta, anótalo como riesgo en el inventario de dependencias externas.
Estrategia 2: capa de adaptador con contrato interno fijo
El patrón más sólido para absorber cambios de versión es introducir una capa de adaptador entre la API externa y el resto del pipeline.
[API externa v1/v2/v3]
↓
[Adaptador — normaliza al modelo interno]
↓
[Pipeline interno — modelo estable]
El adaptador traduce la respuesta de la API al modelo canónico interno. Cuando el proveedor lanza la v3, solo hay que actualizar el adaptador. El pipeline interno no se toca.
Las reglas de diseño de este adaptador:
- Mapeo explícito de campos, nunca pass-through directo del JSON recibido.
- Validación de presencia de campos críticos antes de pasar el dato al siguiente nodo.
- Logging de campos desconocidos: si el proveedor añade un campo que el adaptador no conoce, lo registra pero no falla. Así detectas cambios de esquema antes de que sean un problema.
- Tests de contrato (contract testing) contra un snapshot del esquema esperado, ejecutados en cada build del pipeline.
Estrategia 3: solapamiento de versiones en producción
Cuando el proveedor depreca una versión, el riesgo habitual es que el equipo migre bajo presión y sin margen de validación. La alternativa es diseñar el pipeline para poder enrutar el mismo flujo de datos a dos versiones en paralelo durante un periodo acotado.
def fetch_mentions(query: str, use_legacy: bool = False) -> list:
version = "v1" if use_legacy else "v2"
endpoint = f"https://api.proveedor.com/{version}/mentions"
response = requests.get(endpoint, params={"q": query}, headers=auth_headers())
return normalize(response.json(), schema_version=version)
El flag use_legacy permite activar la versión anterior con un cambio de configuración, sin redeploy. Útil para rollback inmediato si la v2 presenta comportamientos inesperados en producción real.
Este patrón tiene coste: mantener dos adaptadores activos. Pero el coste de un rollback manual en producción a medianoche es mayor.
Estrategia 4: alertas sobre deriva de esquema, no solo sobre errores HTTP
El 80% de los sistemas de monitorización de integraciones B2B alertan sobre fallos HTTP. El 20% alerta sobre deriva de esquema. Deberías estar en ese 20%.
Una alerta de deriva de esquema se dispara cuando:
- Un campo que antes estaba presente en el 95%+ de las respuestas aparece ahora en menos del 60%.
- Un campo numérico empieza a devolver valores fuera del rango histórico esperado.
- Un campo de clasificación devuelve valores no presentes en el catálogo conocido.
Implementar esto no requiere infraestructura compleja. Un script que compara la distribución estadística de los campos en ventanas de 24 horas es suficiente para detectar cambios semánticos silenciosos, que son los más peligrosos porque no generan ningún error visible.
Herramientas como Great Expectations o una implementación propia de validación de schema con JSON Schema ofrecen este nivel de cobertura con coste de implementación moderado.
Cuándo pedir al proveedor un periodo de deprecación garantizado
No todos los proveedores documentan su política de versionado. Antes de comprometer un pipeline crítico con una API externa, vale la pena preguntar explícitamente:
- ¿Cuánto tiempo coexiste la versión antigua con la nueva tras el lanzamiento de la siguiente?
- ¿Hay changelog estructurado (semver, fecha de cambio, campos afectados) o solo release notes narrativos?
- ¿Existe un endpoint de introspección o un schema machine-readable (OpenAPI, JSON Schema) que pueda consultarse programáticamente?
En el ecosistema de APIs de datos como las que expone FeedScale, estas preguntas deberían formar parte del checklist de evaluación del proveedor antes de la integración, no después del primer incidente.
El riesgo que nadie documenta: el cambio semántico sin cambio de versión
El escenario más difícil no es el cambio de versión mayor. Es el cambio silencioso dentro de la misma versión: el proveedor ajusta el modelo de entrenamiento de sentimiento, cambia la granularidad de las categorías temáticas o actualiza la cobertura de fuentes sin anunciarlo como un cambio de versión porque, técnicamente, el esquema JSON no ha variado.
El dato llega. Parsea sin errores. Pero la distribución de valores ha cambiado. El pipeline lo consume. Y el análisis que entrega a negocio empieza a derivar sin que nadie sepa por qué.
La única defensa real contra esto es monitorización estadística continua del dato, no solo monitorización de la interfaz. Tratar el dato como una señal que puede degradarse, no como un objeto binario que llega o no llega.
Eso requiere un cambio de mentalidad: una integración B2B de datos no termina cuando el primer payload llega limpio. Termina cuando hay observabilidad real sobre lo que ese payload significa, versión tras versión.