Respuesta.

Históricamente, la descripción de interfaces entre sistemas ha sido una tarea de arquitectos e integradores, a menudo reduciéndose a intercambios de correos electrónicos con estructuras de datos. Con la llegada de SOA y, más aún, la arquitectura de microservicios, el papel del analista de sistemas en la formalización y el soporte de contratos de integración ha crecido drásticamente.

Problema

Una descripción errónea, incompleta o desactualizada de las interfaces API puede llevar a: incompatibilidad de servicios, aumento en el número de errores, y la imposibilidad de realizar cambios sin causar un fallo en cascada en todo el sistema. En proyectos multiservicio, el número de puntos de integración puede llegar a decenas o cientos.

Solución

El analista de sistemas aplica prácticas modernas:

Formalización de contratos mediante herramientas como OpenAPI/Swagger para REST, protocolos gRPC, WSDL/XSD para SOAP;
Descripción de escenarios típicos de llamada y situaciones de error;
Desarrollo de modelos de eventos (event-driven model) para intercambio en tiempo real;
Mantenimiento de documentación actualizada y autogeneración de contratos;
Aprobación de cambios con los propietarios de todos los servicios implicados.

Un elemento importante es el mantenimiento de versiones correctas y la trazabilidad de cambios en los contratos, así como la integración de casos de prueba para validar interacciones.

Características clave:

Uso de estándares legibles por máquina (OpenAPI/YAML).
Consideración de todos los escenarios de uso y errores.
Comunicación reglamentada entre equipos de diferentes servicios.

Preguntas capciosas.

¿Debería el analista recopilar los requisitos de la API solo de los clientes y desarrolladores internos?

No, es importante involucrar a todos los equipos integrados, considerando los requisitos de socios externos, para evitar lagunas o incompatibilidades.

¿Es posible documentar la API solo en la etapa de entrega del sistema?

No, la especificación de la API se forma y aprueba antes de la implementación; de lo contrario, la compatibilidad hacia atrás se verá afectada en cada etapa.

¿Es la especificación OpenAPI suficiente por sí sola como documentación para todos los casos de intercambio?

No, OpenAPI describe estructuras, pero el analista debe detallar escenarios de interacción (por ejemplo, orden de llamadas, secuencia de eventos, errores de negocio) en la documentación del usuario.

Errores comunes y anti-patrones

Proporcionar una doc desactualizada o una descripción “humana” en lugar de una especificación.
No especificar el manejo de errores y escenarios implícitos.
Falta de control de versiones y trazabilidad de cambios.

Ejemplo de la vida real

Caso negativo: El sistema de logística se integró con transportistas externos. El contrato se describió solo "en palabras". Tras los cambios, se produjeron fallos masivos de integración y retrasos.

Ventajas:

Mínimo esfuerzo inicial

Desventajas:

Fallos masivos
Cambios urgentes
Reputación negativa

Caso positivo: El analista elaboró un OpenAPI con ejemplos de errores/casos exitosos, acordó la versionado, y recopiló retroalimentación de todos los equipos.