Developer tools: cómo auditar el contrato de una API de datos antes de que el pipeline llegue a producción

Developer tools: cómo auditar el contrato de una API de datos antes de que el pipeline llegue a producción

El error llega siempre en el peor momento. El pipeline lleva semanas en producción, los consumidores downstream confían en la estructura del dato, y el proveedor modifica un campo sin preaviso. El campo era opcional según la documentación. Tu código asumía que siempre venía.

La mayoría de estos fallos no son errores de la API. Son errores de auditoría previa. El equipo conectó el pipeline sin verificar el contrato real del dato, solo el contrato documentado. Y ambos raramente coinciden al cien por cien.

Auditar ese contrato antes de integrar —con las herramientas adecuadas y un proceso sistemático— es la diferencia entre un pipeline frágil y uno que aguanta en producción.

Por qué la documentación no es suficiente

La documentación de una API describe la intención del proveedor. No describe el comportamiento real del endpoint bajo distintas condiciones de carga, rangos de fechas, tipos de fuente o combinaciones de filtros poco habituales.

En APIs de datos del universo público, esto se amplifica. El dato subyacente es heterogéneo por naturaleza: fuentes distintas producen estructuras distintas, idiomas distintos, volúmenes distintos. La API normaliza lo que puede. Lo que no puede normalizar, lo pasa como viene o lo omite.

Los campos declarados como required pueden aparecer vacíos en registros de fuentes legacy. Los campos declarados como string pueden contener arrays serializado como texto en ciertos proveedores. Los timestamps pueden variar entre ISO 8601 con zona horaria y Unix epoch dependiendo del endpoint.

La documentación no te cuenta esto. Solo la inspección del dato real lo hace.

Paso 1: construye un corpus de muestras representativo antes de escribir código de producción

El primer instrumento no es un framework ni una librería. Es disciplina de muestreo.

Antes de diseñar el schema de tu pipeline, realiza al menos 200-500 llamadas reales al endpoint, variando:

• Rango temporal: no solo datos recientes. Los registros históricos suelen tener estructura distinta.
• Combinaciones de filtros: idioma, región, tipo de fuente, categoría temática.
• Paginación extrema: primeras páginas, últimas páginas, páginas intermedias de un cursor largo.

Serializa todas las respuestas en crudo. No las proceses aún. El objetivo es tener un corpus real del que extraer el contrato empírico.

# Ejemplo: recolectar 300 respuestas crudas variando el parámetro q
for i in $(seq 1 300); do
  curl -s "https://api.example.com/v2/mentions?q=term_${i}&lang=es" \
    >> corpus/raw_responses.ndjson
  sleep 0.2
done

Paso 2: extrae el contrato empírico con herramientas de inferencia de esquema

Con el corpus en mano, usa herramientas de inferencia de esquema para extraer lo que la API realmente entrega, no lo que dice entregar.

genson (Python) infiere JSON Schema desde ejemplos reales:

from genson import SchemaBuilder
import json

builder = SchemaBuilder()

with open("corpus/raw_responses.ndjson") as f:
    for line in f:
        builder.add_object(json.loads(line))

schema = builder.to_schema()
with open("inferred_schema.json", "w") as out:
    json.dump(schema, out, indent=2)

El esquema resultante te dirá qué campos aparecen siempre, cuáles son opcionales de facto, y qué tipos reales tienen. Compara esto contra la documentación oficial. Las diferencias son tu lista de riesgos.

jsonschema te permite luego validar cada registro del pipeline contra ese contrato:

import jsonschema, json

schema = json.load(open("inferred_schema.json"))
record = json.loads(some_api_response)

try:
    jsonschema.validate(instance=record, schema=schema)
except jsonschema.ValidationError as e:
    log_anomaly(e.message, record)

Valida en la capa de ingestión, no en la de transformación. Los errores de contrato deben cortarse lo antes posible.

Paso 3: prueba los casos límite que el proveedor no documenta

Una vez tienes el esquema empírico, diseña casos de prueba explícitos para los escenarios que el proveedor no documenta:

• Campo nulo vs. campo ausente: ¿el API omite la clave o la incluye con null? Tu código debe manejar ambos.
• Strings vacíos: ¿"" y null tienen el mismo significado semántico en este campo?
• Arrays de un solo elemento vs. objeto: algunos proveedores serializan arrays de un elemento como objeto directo. Es un error clásico que rompe parsers tipados.
• Caracteres especiales en campos de texto: saltos de línea dentro de strings JSON, caracteres Unicode en rangos no BMP, comillas escapadas de forma inconsistente.

Documenta cada caso en un archivo de fixtures. Esos fixtures pasan a ser parte de tu suite de tests de integración y se ejecutan en cada despliegue:

tests/
  fixtures/
    missing_field_author.json
    null_vs_empty_body.json
    single_element_array.json
    unicode_edge_case.json
  test_api_contract.py

Paso 4: monitoriza la deriva del contrato en producción

Auditar el contrato antes del despliegue no es suficiente si el proveedor puede cambiarlo después. Necesitas detección de deriva en tiempo real.

Implementa un validador ligero en la capa de ingestión que, sin bloquear el pipeline, registre anomalías de esquema:

def ingest_record(record: dict):
    violations = validate_against_contract(record)
    if violations:
        metrics.increment("contract_drift", tags={"field": violations[0].field})
    # el pipeline continúa aunque haya deriva — el dato no se descarta,
    # se etiqueta para revisión posterior
    store(record, flagged=bool(violations))

Con este patrón, la deriva del contrato se convierte en una señal observable. Cuando el número de violaciones supera un umbral, recibes una alerta antes de que el problema llegue a los consumidores downstream.

En plataformas como FeedScale, donde el volumen de registros procesados puede escalar sin aviso según la actividad del universo público, este tipo de monitorización es lo que separa un pipeline que aguanta de uno que acumula deuda técnica silenciosa.

El contrato real no está en la documentación: está en el dato

La documentación es una promesa. El corpus de muestras es la realidad. La distancia entre ambos es tu riesgo técnico.

Antes de integrar cualquier API de datos en un pipeline de producción, invierte el tiempo que sea necesario en muestrear, inferir, validar y monitorizar el contrato real. Es trabajo que no aparece en el roadmap, pero que evita los incidentes que sí aparecen en los postmortems.

Los mejores pipelines no son los que nunca fallan. Son los que detectan el fallo antes de que el consumidor lo vea.

← Volver al blog