Ответ.

Исторически описание интерфейсов между системами было уделом архитекторов и интеграторов, часто сводилось к обмену email со структурой данных. В эпоху SOA и тем более микросервисной архитектуры роль системного аналитика в формализации и поддержке интеграционных контрактов резко выросла.

Проблема

Ошибочное, неполное или устаревшее описание API-интерфейсов становится причиной: несовместимости сервисов, роста количества багов, невозможности изменений без каскадного нарушения работы всей системы. В мультисервисных проектах число точек интеграции достигает десятков и сотен.

Решение

Системный аналитик применяется современные практики:

• формализация контрактов через инструменты типа OpenAPI/Swagger для REST, gRPC-протоколы, WSDL/XSD для SOAP;
• описание типовых сценариев вызова и ошибочных ситуаций;
• разработка схем событий (event-driven model) для обмена в реальном времени;
• ведение актуальной документации и автогенерация контрактов;
• согласование изменений с владельцами всех затрагиваемых сервисов.

Важный элемент — ведение корректной версионности и трассировки изменений контрактов, а также интеграция тест-кейсов для валидации взаимодействий.

Ключевые особенности:

• Использование машиночитаемых стандартов (OpenAPI/YAML).
• Учет всех сценариев использования и ошибок.
• Регламентированная коммуникация между командами разных сервисов.

Вопросы с подвохом.

Должен ли аналитик собирать требования к API только с заказчика и внутренних разработчиков?

Нет, важно вовлекать все интегрируемые команды, учитывать требования внешних партнеров, чтобы избежать пробелов или несовместимости.

Можно ли документировать API только на этапе сдачи системы?

Нет, спецификация API формируется и согласуется еще до реализации, иначе обратная совместимость будет нарушена на каждом этапе.

Является ли OpenAPI-спецификация сама по себе достаточной документацией для всех случаев обмена?

Нет, OpenAPI описывает структуры, но сценарии взаимодействия (например, порядок вызова, последовательность событий, бизнес-ошибки) аналитик обязан расписать в пользовательской документации.

Типовые ошибки и анти-паттерны

• Выдавать устаревший doc или "человеческое" описание вместо спецификации.
• Не прописывать обработку ошибок, неявные сценарии.
• Отсутствие контроля версий и трассировки изменений.

Пример из жизни

Негативный кейс: Система логистики интегрировалась с внешними перевозчиками. Контракт описали только "в словах". После выхода изменений произошли массовые отказы интеграции, задержки.

Плюсы:

• Минимальные трудозатраты на старте

Минусы:

• Массовые сбои
• Срочные доработки
• Отрицательная репутация

Положительный кейс: Аналитик составил OpenAPI c примерами ошибок/успешных сценариев, согласовал версионирование, собрал фидбек от всех команд.

Плюсы:

• Бесшовная интеграция новых партнеров
• Снижение времени на on-boarding
• Прозрачные доработки

Минусы:

• Временные затраты на согласование
• Требуется погружение в технический стек