Answer.

Historically, the description of interfaces between systems was the concern of architects and integrators, often reduced to email exchanges with data structure. In the era of SOA and especially microservice architecture, the role of the system analyst in formalizing and supporting integration contracts has significantly increased.

Problem

Incorrect, incomplete, or outdated descriptions of API interfaces lead to: service incompatibility, an increase in bugs, and the inability to make changes without cascading disruptions to the entire system. In multi-service projects, the number of integration points can reach dozens or hundreds.

Solution

The system analyst applies modern practices:

formalizing contracts through tools like OpenAPI/Swagger for REST, gRPC protocols, WSDL/XSD for SOAP;
describing typical call scenarios and error situations;
developing event schemas (event-driven model) for real-time communication;
maintaining up-to-date documentation and auto-generating contracts;
coordinating changes with the owners of all affected services.

An important element is maintaining correct versioning and change tracking of contracts, as well as integrating test cases for validating interactions.

Key features:

Use of machine-readable standards (OpenAPI/YAML).
Consideration of all usage scenarios and errors.
Regulated communication between teams of different services.

Tricky questions.

Should an analyst gather API requirements only from the client and internal developers?

No, it is important to involve all integrated teams and consider the requirements of external partners to avoid gaps or incompatibility.

Can APIs be documented only at the system delivery stage?

No, the API specification is formed and agreed upon even before implementation; otherwise, backward compatibility will be violated at every stage.

Is the OpenAPI specification itself sufficient documentation for all exchange cases?

No, OpenAPI describes structures, but the interaction scenarios (e.g., order of calls, sequence of events, business errors) must be detailed by the analyst in user documentation.

Common mistakes and anti-patterns

Providing outdated documentation or "human" descriptions instead of specifications.
Failing to specify error handling, implicit scenarios.
Lack of version control and change tracking.

Example from life

Negative case: The logistics system was integrated with external carriers. The contract was described only "in words". After updates, there were widespread integration failures and delays.

Pros:

Minimal effort at the start

Cons:

Widespread failures
Urgent revisions
Negative reputation

Positive case: The analyst created an OpenAPI with error/success scenario examples, coordinated versioning, and collected feedback from all teams.