Data APIs: cómo detectar cambios silenciosos en el esquema antes de que rompan tu pipeline

Data APIs: cómo detectar cambios silenciosos en el esquema antes de que rompan tu pipeline

Hay un tipo de fallo que no genera alertas inmediatas, no levanta excepciones en el momento justo y no aparece en los logs del servidor hasta que el daño ya está hecho. Son los cambios silenciosos de esquema: un campo que pasa de string a integer, un array que ahora devuelve null en lugar de vacío, una clave que desaparece sin que la versión de la API cambie. El proveedor no lo llama breaking change. Tú lo descubres cuando el modelo de análisis lleva tres días ingiriendo basura.

Este problema es especialmente crítico en integraciones con data APIs de contenido público, donde el volumen de señales es alto y la verificación manual es inviable. No puedes revisar registro a registro. El fallo se propaga silenciosamente hasta que un dashboard muestra números imposibles o un proceso de enriquecimiento empieza a fallar sin causa aparente.

La solución no es confiar más en el proveedor. Es construir una capa de defensa propia.

Por qué los esquemas cambian sin versionar

Las APIs bien gestionadas siguen semver estricto: cualquier cambio incompatible implica una versión mayor. En la práctica, muchos proveedores distinguen entre "cambios que rompen" y "cambios aditivos" de forma subjetiva. Añadir un campo nuevo no se considera breaking. Pero si tu código hace deserialización estricta, ese campo nuevo inesperado puede levantar un error. Si el campo opcional que dabas por supuesto desaparece, tu lógica de negocio falla en silencio porque el campo tenía un valor por defecto implícito en tu código.

El problema de fondo es que el contrato de una API REST no es el código del servidor, sino la documentación. Y la documentación siempre va por detrás de la implementación.

Validación de esquema en tiempo de ingesta: el primer cortafuegos

La defensa más efectiva es validar cada respuesta contra un esquema definido por ti, no por el proveedor. Herramientas como JSON Schema o librerías como pydantic (Python) o zod (TypeScript) permiten definir qué estructura esperas y rechazar o alertar ante cualquier desviación.

Un ejemplo mínimo en Python con pydantic:

from pydantic import BaseModel, ValidationError
from typing import Optional, List

class Mention(BaseModel):
    id: str
    published_at: str
    text: str
    source_url: Optional[str] = None
    sentiment_score: Optional[float] = None

def ingest_mentions(raw_items: List[dict]):
    validated = []
    for item in raw_items:
        try:
            validated.append(Mention(**item))
        except ValidationError as e:
            log_schema_alert(item, e)  # No rompe el pipeline, pero registra la anomalía
    return validated

Lo importante aquí no es rechazar el dato automáticamente, sino registrar la anomalía y seguir procesando lo que sí es válido. Un rechazo total detiene la ingesta; una alerta con fallback mantiene el sistema vivo mientras investigas.

Monitorización activa del esquema: más allá de la ingesta

La validación en tiempo real es necesaria pero no suficiente. También necesitas tendencias: ¿el campo sentiment_score viene nulo en el 2% de los registros o en el 40%? ¿Ese porcentaje ha cambiado esta semana respecto a la anterior?

Un esquema de monitorización útil en producción incluye:

• Tasa de campos nulos por clave: si un campo habitualmente poblado empieza a llegar vacío, algo ha cambiado upstream.
• Distribución de tipos por campo: detecta conversiones implícitas (un boolean que empieza a llegar como "true" string).
• Cardinalidad de enumerados: si un campo de categoría tenía 8 valores posibles y ahora tiene 12, hay valores nuevos no mapeados en tu lógica.
• Latencia de publicación por fuente: no es un cambio de esquema, pero un proveedor que empieza a entregar señales con 6 horas de retraso afecta igual a tu pipeline de análisis en tiempo real.

Puedes implementar esto con cualquier sistema de métricas (Prometheus + Grafana, Datadog, incluso una tabla en PostgreSQL con agregaciones diarias). El coste de implementar este sistema es bajo. El coste de no tenerlo aparece cuando ya has procesado semanas de datos incorrectos.

Gestión de versiones del esquema propio: el contrato interno

Cuando el proveedor cambia su API, tu sistema necesita absorber ese cambio sin reescribir toda la integración. La clave es desacoplar el esquema de la API del modelo de datos interno.

Define un schema mapper explícito: una capa de transformación que convierte la respuesta cruda del proveedor en tu modelo canónico interno. Si el proveedor cambia published_at por publication_date, solo tienes que actualizar el mapper, no todos los módulos que consumen el dato.

def map_mention(raw: dict) -> dict:
    return {
        "id": raw.get("id") or raw.get("uuid"),
        "published_at": raw.get("published_at") or raw.get("publication_date"),
        "text": raw.get("text") or raw.get("body") or raw.get("content"),
        "source_url": raw.get("source_url") or raw.get("url"),
    }

Esta función puede parecer trivial, pero es el punto exacto donde absorbes la variabilidad del proveedor. Versiona este mapper junto con tu código. Cada cambio en el proveedor queda registrado en el historial de commits.

Cuándo el cambio de esquema no es el problema, sino el síntoma

A veces la raíz del problema no está en el esquema sino en la semántica. El campo relevance_score sigue siendo un float entre 0 y 1, pero el proveedor ha cambiado el algoritmo de cálculo internamente. El esquema es idéntico. Los valores son distintos. Tu modelo downstream estaba calibrado con la distribución anterior.

Este tipo de deriva semántica es más difícil de detectar porque no falla en la validación. Solo aparece en el análisis de distribuciones a lo largo del tiempo: si el percentil 90 de relevance_score era 0.72 y ahora es 0.41, algo ha cambiado que no está en la documentación.

Las plataformas como FeedScale están diseñadas para entregar señales del universo público con estabilidad estructural, pero incluso en entornos controlados la monitorización semántica aporta una capa de confianza que ningún contrato puede garantizar por sí solo.

El pipeline que sí detecta lo que no documenta el proveedor

Un sistema robusto ante cambios de esquema tiene cuatro capas:

1. Validación estructural en ingesta (tipos, campos obligatorios, rangos).
2. Alertas por anomalías estadísticas (distribuciones, tasas de nulos, cardinalidades).
3. Mapper explícito y versionado entre el modelo del proveedor y tu modelo interno.
4. Monitorización semántica de los valores, no solo de la estructura.

No necesitas implementar las cuatro desde el día uno. Pero si llevas más de dos semanas en producción con una integración de datos sin ninguna de estas capas, estás asumiendo un riesgo que no está cuantificado en tu arquitectura.

Los datos que no puedes confiar no son datos. Son ruido estructurado.

← Volver al blog