Una integración confiable asume que la red falla, los mensajes se repiten y las dependencias responden más lento de lo esperado.
Contratos explícitos y versionados
El contrato debe describir datos, validaciones, errores y expectativas operativas. OpenAPI ayuda a documentar y automatizar, pero la compatibilidad depende de una disciplina: agregar campos suele ser seguro; cambiar significados o eliminar valores requiere una estrategia de versión y migración.
Idempotencia como requisito
Las operaciones de pago, facturación o inventario no pueden duplicarse porque un cliente repitió una solicitud. Una clave de idempotencia, almacenada junto al resultado, permite responder de manera consistente ante reintentos.
Fallar de manera controlada
- Timeouts explícitos y menores que el presupuesto total de la operación.
- Reintentos limitados, con espera incremental y variación aleatoria.
- Circuit breakers para evitar insistir sobre una dependencia degradada.
- Colas y procesamiento asíncrono cuando la respuesta inmediata no es necesaria.
- Dead-letter queues con visibilidad y procedimientos de reproceso.
Errores útiles y seguros
Los consumidores necesitan códigos estables y mensajes accionables. Los detalles internos pertenecen a logs protegidos, no a la respuesta pública. Un identificador de correlación permite unir ambas perspectivas sin revelar información sensible.
Operar el contrato
Las pruebas de contrato, métricas por consumidor y políticas claras de retiro reducen sorpresas. Una API no termina cuando responde en producción: necesita observabilidad, capacidad, seguridad, documentación y un proceso de evolución.