Data APIs: por qué leer el contrato de datos antes de conectar el pipeline salva semanas de trabajo

Data APIs: por qué leer el contrato de datos antes de conectar el pipeline salva semanas de trabajo

El equipo lleva tres días depurando un pipeline que en staging funcionaba sin problemas. En producción, los registros llegan con campos nulos que el modelo de downstream no tolera, el rate limit se agota en las primeras horas del día y la documentación oficial no menciona ninguno de los dos comportamientos. El problema no estaba en el código. Estaba en que nadie leyó —o exigió— el contrato de datos real de la API antes de conectarla.

Las data APIs no son servicios genéricos. Cada una lleva consigo un conjunto de decisiones de diseño —muchas de ellas implícitas— que afectan directamente a la estabilidad del pipeline, al coste operativo y a la calidad de los análisis derivados. Conectar sin auditar ese contrato es técnicamente equivalente a integrar una dependencia de terceros sin revisar su licencia: funciona hasta que no funciona, y cuando falla, lo hace en el peor momento.

Este post describe qué elementos forman ese contrato de datos, cómo auditarlos antes de la primera llamada en producción y qué señales indican que la API no está lista para el caso de uso que tienes en mente.

El contrato de datos no siempre está en la documentación oficial

La documentación de una API describe lo que el proveedor quiere que veas. El contrato real incluye además lo que el proveedor no ha documentado pero que igualmente sucede en producción.

Algunos ejemplos habituales:

• Campos opcionales que se omiten en lugar de entregarse vacíos. Un campo author puede estar presente en el 95 % de los registros, pero el 5 % restante simplemente no lo incluye. Si el pipeline asume que el campo siempre existe, el schema validator falla silenciosamente o, peor, propaga un null aguas abajo.
• Ventanas de tiempo con comportamiento diferente. Muchas APIs de datos del universo público tienen latencias distintas según la antigüedad de los registros. Los datos recientes pueden tardar en indexarse; los históricos pueden devolverse en orden no cronológico.
• Rate limits de facto distintos a los documentados. El límite oficial puede ser de 100 req/min, pero la API empieza a responder con 429 a partir de ráfagas de 30 req/10 s. Ese comportamiento no suele estar en el README.

Para descubrir el contrato real, la estrategia más efectiva es simple: ejecutar una batería de llamadas de prueba en condiciones de producción —no en sandbox— y registrar el comportamiento completo, incluidas las respuestas de error, los tiempos de respuesta p95 y la variabilidad en la estructura de los payloads.

Qué auditar antes de conectar en producción

Una auditoría mínima antes de integrar una data API debería cubrir estos cinco puntos:

1. Cardinalidad y opcionalidad de campos

Toma una muestra de al menos 1.000 registros reales y calcula la tasa de presencia de cada campo. Cualquier campo con presencia inferior al 100 % debe tratarse como opcional en el schema, aunque la documentación lo marque como obligatorio.

from collections import Counter

def field_coverage(records: list[dict]) -> dict:
    total = len(records)
    counts = Counter()
    for record in records:
        for key in record:
            counts[key] += 1
    return {k: round(v / total, 4) for k, v in counts.items()}

Este fragmento tarda menos de cinco minutos en implementarse y puede ahorrarte días de debugging en producción.

2. Distribución real de latencia de respuesta

No te quedes con el tiempo de respuesta promedio. Mide el p50, p90 y p99. Si el p99 supera el timeout que has configurado en el cliente HTTP, tendrás errores intermitentes que serán difíciles de reproducir.

3. Comportamiento ante errores transitorios

¿La API devuelve Retry-After en los 429? ¿Los 503 son recuperables o señalan mantenimiento prolongado? ¿Los 408 incluyen el request ID para poder correlacionar en logs? Un proveedor que no instrumenta sus errores añade carga de debugging al equipo que integra.

4. Consistencia del orden de entrega

Si el pipeline depende de procesar registros en orden cronológico, verifica que la API garantiza ese orden explícitamente. Muchas APIs de datos no lo garantizan: el orden de entrega depende del orden de indexación, que puede diferir del orden de publicación.

5. Semántica del cursor de paginación

Un cursor basado en offset numérico tiene un problema conocido: si se insertan registros mientras paginas, puedes saltar registros o recibirlos duplicados. Un cursor opaco basado en un identificador de posición es más robusto, pero debes verificar que no expira entre páginas.

Las señales de que la API no encaja con tu caso de uso

Más allá de la auditoría técnica, hay señales de nivel contractual que indican que la integración va a ser costosa a largo plazo:

• No hay changelog público. Un proveedor que no comunica cambios de schema o de comportamiento es un proveedor que puede romper tu pipeline sin previo aviso. Esto no es hipotético; es el escenario más frecuente en integraciones B2B de APIs de datos.
• El modelo de cuota no es predecible. Si el coste por llamada varía según el peso del payload, el tipo de consulta o la franja horaria, el modelo financiero del pipeline se vuelve imposible de proyectar. Un modelo pay-as-you-go bien diseñado —como el que usa FeedScale— debería tener unidades de consumo claras y auditables desde el primer momento.
• No existe un endpoint de introspección o health check. Si no puedes saber el estado del servicio sin hacer una llamada real, el pipeline no puede implementar circuit breaker de forma inteligente.
• La documentación y el comportamiento real difieren en más de un 10 %. Este umbral es subjetivo, pero si durante la auditoría encuentras más de uno o dos comportamientos no documentados relevantes, el coste de mantenimiento de la integración será estructuralmente alto.

Antes de firmar el contrato implícito

Toda integración con una data API es, en la práctica, un acuerdo: el pipeline asume ciertos comportamientos del proveedor, y el proveedor los entrega (o no) de forma consistente. La diferencia entre una integración que dura meses y una que se rediseña a las pocas semanas suele estar en si ese acuerdo se hizo explícito antes de conectar los sistemas.

La auditoría técnica descrita aquí no es un proceso largo. Con los fragmentos correctos y una muestra representativa de datos reales, se puede ejecutar en menos de medio día. El coste de no hacerla se paga mucho más caro: en horas de debugging, en datos perdidos y en confianza erosionada del equipo en la infraestructura.

Si estás evaluando APIs de datos para análisis del universo público de Internet —menciones, tendencias, señales de cobertura mediática—, vale la pena exigir estas garantías desde la primera conversación técnica con el proveedor. FeedScale expone su modelo de consumo y comportamiento de forma auditables antes de que el pipeline llegue a producción. Ese nivel de transparencia no debería ser la excepción.

← Volver al blog