Developer tools: cómo testear contratos de API de datos antes de que produccción los rompa

Developer tools: cómo testear contratos de API de datos antes de que producción los rompa

Muchos equipos descubren que su integración con una API externa falla el mismo día en que más la necesitan. No es mala suerte. Es que nunca se testeó el contrato real: lo que la API promete entregar frente a lo que el sistema consumidor espera recibir. Hay una brecha entre ambos, y esa brecha vive felizmente invisible hasta que el pipeline cae en producción.

El problema no es la falta de tests. La mayoría de equipos tiene tests unitarios, tests de integración, incluso algún smoke test al arrancar. El problema es que ninguno de esos tests modela el comportamiento de la API externa como un proveedor que puede cambiar silenciosamente sus compromisos: campos que desaparecen, tipos que cambian, paginaciones que se reorganizan. Testear tu código no es lo mismo que testear el contrato con el servicio del que dependes.

Este post describe un conjunto de prácticas y herramientas concretas para atacar ese problema antes de que llegue a producción.

Qué es un contrato de API y por qué se rompe sin avisar

Un contrato de API es el acuerdo implícito o explícito entre el proveedor y el consumidor: qué campos existen, qué tipos tienen, qué valores son válidos, qué significa un error 4xx frente a uno 5xx. En APIs REST bien documentadas, ese contrato está en una especificación OpenAPI. En APIs del mundo real, está en la documentación PDF que no se actualiza y en el comportamiento observado en producción.

Los contratos se rompen de formas predecibles:

• Un campo opcional pasa a estar ausente en ciertos contextos (geografía, idioma, tipo de fuente).
• Un campo que antes era string ahora puede ser null o un array.
• El orden de los resultados cambia sin previo aviso.
• Los códigos de error se reciclan para significar cosas distintas.

Cada uno de estos cambios, por pequeño que parezca, puede silenciar datos en tu pipeline o provocar excepciones no controladas aguas abajo. Si procesas señales de fuentes públicas a escala, un campo ausente en el 3 % de los registros representa un volumen de datos que ningún test ad hoc detecta.

Contract testing: la práctica que más equipos saltan

El contract testing no es un test de integración clásico. No prueba que tu código funciona. Prueba que el proveedor sigue cumpliendo lo que prometió.

La aproximación más madura es consumer-driven contract testing: el consumidor define sus expectativas en un fichero de contrato (Pact es el estándar de facto), ese fichero se publica en un broker, y el proveedor verifica periódicamente que sus respuestas siguen satisfaciendo esas expectativas. Si el proveedor cambia algo que rompe un contrato registrado, el sistema lo detecta antes del despliegue.

En la práctica, para APIs externas que no controlas, el flujo es diferente. No puedes pedirle al proveedor que ejecute tus contratos. Lo que sí puedes hacer es:

1. Registrar el esquema observado en producción con herramientas como json-schema-inferrer (Java) o genson (Python). Construyes un esquema a partir de respuestas reales, no de documentación.
2. Validar cada respuesta contra ese esquema en staging y en un porcentaje de tráfico real. Si el esquema cambia, el validador lo detecta y emite una alerta antes de que el cambio envíe datos corruptos al almacén.
3. Versionar el esquema observado en tu repositorio como si fuera código. Cada cambio de esquema genera una PR con diff explícito. Así, nadie descubre el cambio en un postmortem.

Simulación de fallos: el lado del tooling que más se subestima

Saber que tu código procesa correctamente una respuesta válida no es suficiente. Necesitas saber qué hace cuando la API responde de formas inesperadas bajo carga real.

Herramientas como WireMock o Mountebank permiten simular comportamientos de API que en producción son difíciles de forzar:

• Latencia variable: ¿tu cliente tiene timeout bien configurado? ¿el circuit breaker se activa correctamente?
• Respuestas parciales: ¿qué pasa si el body llega truncado?
• Errores intermitentes al 20 % de las peticiones: ¿tu lógica de retry duplica datos o los pierde?
• Cambios de esquema deliberados: eliminar un campo, cambiar su tipo. ¿El pipeline falla ruidosamente o en silencio?

Ejecutar estas simulaciones en un entorno de staging con tráfico sintético representativo del volumen real es lo que separa un sistema que "funciona en la demo" de uno que aguanta producción.

Snapshot testing de respuestas: más útil de lo que parece

El snapshot testing es una técnica habitual en frontend (Jest) que muchos equipos de backend subestiman para integraciones con APIs externas.

La idea es simple: guardar respuestas reales de la API como fixtures y comparar nuevas respuestas contra esas referencias en cada ejecución de CI. Cualquier diferencia genera un fallo explícito que requiere revisión consciente.

No es un test que falla cuando la API cambia algo malo y pasa cuando no cambia nada. Es un test que te obliga a decidir activamente si un cambio en la respuesta es esperado o no. Esa decisión consciente es exactamente lo que evita que un cambio silencioso de esquema llegue a producción sin revisión.

Para pipelines que procesan señales del universo público de Internet —donde la heterogeneidad de fuentes y la variabilidad de los datos es alta—, este patrón ahorra muchas horas de depuración. FeedScale, por ejemplo, expone respuestas JSON estructuradas con campos que pueden variar según el tipo de señal o fuente; tener snapshots de cada variante cubre los casos edge que la documentación no siempre anticipa.

Un flujo mínimo viable de tooling antes del despliegue

Si partes de cero, este es el orden razonable de implementación:

1. Inferencia y versionado de esquema: herramienta automática que registra el esquema observado tras cada despliegue.
2. Validación en staging: middleware que valida cada respuesta de API contra el esquema versionado y emite métricas de desviación.
3. Mocks con escenarios de error: WireMock o equivalente en el entorno de CI, con al menos 5-6 escenarios de fallo realistas.
4. Snapshot tests de fixtures: una suite pequeña pero actualizada de respuestas reales como referencia en CI.
5. Alertas de drift en producción: sampling del 5-10 % del tráfico real validado contra el esquema, con alertas en el observability stack.

No es un sistema que se construye en un sprint. Pero cada capa añade una línea de defensa que reduce el radio de impacto de cambios en APIs externas que no controlas.

El contrato entre tu sistema y una API externa no es solo la documentación. Es la suma de todos los comportamientos que has observado, versionado y probado. Si ese registro no existe, el contrato real lo escribirá producción en el peor momento posible.

¿Tu pipeline ya tiene esas capas de defensa? Puedes explorar cómo FeedScale estructura sus respuestas para facilitar este tipo de validación en integraciones B2B de alto volumen.

← Volver al blog