Antes de integrar, armá el laboratorio

Una solución aparte, aislada y sin ruido, donde probás la integración antes de meterla en tu sistema. Qué se rompe de verdad, contra qué conviene pegarle, y qué te llevás de vuelta al proyecto real.

Llegó ese día: tenías que integrar una API de terceros. La metiste en tu sistema y de golpe empezaron a aparecer errores en los logs.

Entrás a analizarlos y te das cuenta de que estás metido en una bolsa de gatos. La integración se volvió difícil de testear, perdiste la colección de Postman — o peor, la tenés y no te sirve.

Ahí aparece la necesidad: revisar la integración en un entorno controlado, sin contaminación.

Y esa es la sugerencia que le hago a mi equipo: antes de integrar, armá un laboratorio.

#Postman no prueba lo que creés que prueba

Este es el malentendido que hace que casi todos se salteen este paso.

Postman prueba su API. Confirma que el proveedor responde, que el contrato es más o menos el que dice la documentación, que tus credenciales andan.

El laboratorio prueba tu código contra su API. Que es otra cosa completamente distinta.

Postman no te va a mostrar cómo deserializa eso en C#. Ni qué excepción sale cuando el proveedor tarda de más. Ni qué pasa con tu HttpClient cuando le mandás mil llamadas en vez de una. Ni si tu reintento generó un cobro duplicado.

Una request suelta que devuelve 200 no te dice nada de eso.

#Qué es el laboratorio

Un proyecto completamente de cero, limpio, aislado. Sin el ruido del sistema grande.

Ahí escribís los métodos principales de consumo, definís los contratos y te asegurás de que funcione — incluido con volumen alto. Como está aislado, hasta podés meterle un benchmark y medir esa librería contra otra opción antes de casarte con una.

En la práctica varío entre dos formas, y el criterio es simple:

• App de consola para la mayoría de los casos. Instalás las librerías y las configurás a mano.
• Web API cuando es algo más específico y no quiero invertir tiempo en armar la inyección de dependencias. Ahí ya te viene configurada.

Depende de la complejidad de lo que estés integrando. Lo importante no es cuál elegís, es que esté aislado.

Ese aislamiento es todo el punto: en un proyecto grande estos problemas también aparecen, pero mezclados con los tuyos y tapados por veinte capas. En el laboratorio se ven. Mi estimación, después de hacer esto varias veces, es que te ahorrás cerca del 90% de los errores que esa integración te iba a dar en producción.

#Qué se rompe de verdad

Esta es la lista por la que escribo laboratorios:

Timeouts y 429. El proveedor tarda, corta, o te frena por rate limit. Y ahí aparece la pregunta que casi nadie se hace a tiempo: ¿reintentás? ¿cuántas veces? ¿con qué espera entre intentos?

Volumen. Todo anda con una request. Las pruebas bulk son otra historia: ahí salen los límites del proveedor, y también los tuyos.

Deserialización. El JSON no vino como decía la doc y quedó deserializado a nulls o a valores por defecto, sin tirar un solo error. Se rompe tres capas más adelante, lejos de la causa.

Idempotencia. Esta es la que más caro sale. Si reintentaste por un timeout, ¿la primera llamada llegó igual? Si el proveedor no es idempotente, tu reintento no fue un reintento: fue un segundo pedido, un segundo cobro, un segundo envío. Y es un problema que solo aparece cuando combinás fallas con reintentos y volumen — exactamente lo que el laboratorio te deja provocar a pedido.

El acoplamiento. Esta es la más profunda, y no es un error de ejecución: es una decisión de diseño. ¿Qué es responsabilidad de la integración y qué de tu sistema? ¿El reintento lo maneja el cliente de la API o el que lo llama? ¿El mapeo del modelo de ellos al tuyo va adentro o afuera? ¿Quién decide qué hacer cuando falla?

Si no definís eso en el laboratorio, lo vas a definir apurado y adentro de tu código, con el proveedor filtrándose por todos lados.

#Contra qué pegarle

Depende de la necesidad, y no siempre hay una sola opción:

• Sandbox del proveedor, cuando existe y cuando es fiel. Ojo con esa segunda condición.
• Ambiente de desarrollo o testing, si el proveedor te da uno de verdad.
• Producción, solo lectura, cuando el sandbox miente o directamente no existe.

Esa última merece una advertencia. Si vas a pegarle a producción para entender el comportamiento real, es exactamente el escenario donde un guard de escritura se gana el sueldo: el laboratorio es un proyecto suelto, hecho rápido, sin las protecciones del sistema grande. Es el lugar más fácil del mundo para mandar un POST sin querer.

#Qué te llevás de vuelta

El entregable del laboratorio no es "anda". Es esto:

• La información mínima y necesaria para que la implementación salga bien de una.
• Una distribución de responsabilidades ya resuelta — decidida con calma, no en medio de un incidente.
• Claridad sobre las razones probables de error, que es lo que te permite manejarlas en serio en vez de envolver todo en un try/catch y rezar.
• Una implementación concreta y reutilizable, que después inyectás con su interfaz.

// Lo que sale del laboratorio es el contrato, no el detalle
public interface IShippingProvider
{
    Task<ShipmentResult> CreateAsync(ShipmentRequest request, CancellationToken ct);
}

Y ese último punto tiene una cola larga: como la pieza nació aislada, no está atada a tu sistema. Si mañana otro proyecto necesita la misma integración, ya la tenés. Si algún día te la piden como paquete, tampoco hace falta desarmar nada — la podés publicar como NuGet.

Es la única forma de reuso que no se paga después: la que salió aislada desde el principio, no la que hay que despegar de un sistema que ya la absorbió.

#Lo que queda

El laboratorio no es tiempo perdido antes de empezar. Es el único momento en que podés equivocarte con la integración sin que le importe a nadie.

Después ya no es un experimento: es código en tu sistema, con usuarios del otro lado y un incidente esperando su turno.

#integration #testing #dotnet #api