Что следует знать о требованиях к интеграциям: роль бизнес-аналитика, когда вы – владелец или потребитель API – часть 2
- Ganna Kaplun
- 22 часа назад
- 4 мин. чтения
В первой части мы разобрали, что такое API-контракт, из чего он состоит и какие нефункциональные требования следует учитывать. Теперь посмотрим на интеграцию с двух сторон: когда ваша команда предоставляет API, и когда использует чужой. Для бизнес-аналитика оба сценария - это разные роли в общей игре, но с одинаковой целью: сделать взаимодействие предполагаемым, стабильным и управляемым.
Когда вы - собственник API
Быть владельцем (owner) API означает, что ваша система открывает некоторые данные или функции для других. Вы определяете "язык общения" - то есть контракт.
Для бизнес-аналитика эта роль означает:
сформулировать требования к тому, что именно открывается для публичного доступа и каким образом;
согласовывать ожидания с потребителями API;
обеспечить понятную документацию и процесс поддержки.
Что должно быть в требованиях к собственному API
Цель и сценарий использования.Опишите, для чего именно нужен API: кто будет его вызывать, в каких бизнес-процессах.
Пример требования:
API используется партнерами для создания заказов и проверки статуса доставки.
Доступ и ограничения.
Кто может использовать API (внутренние системы, внешние партнеры)?
Какие методы авторизации применяются (API key, token)?
Какие лимиты запросов (rate limits)?
Пример требования:
API является публично доступным с доступом через АРІ-ключ, активный в течение подписки.
Форматы запросов и ответов.
Основная структура данных (JSON, XML тощо);
Примеры правильных и ошибочных зарпосов.
Пример требования:
Если пользователь не имеет доступа к ресурсу, API возвращает код 403 Forbidden с описанием в поле message.
Коммуникация изменений.
Как вы предупреждаете о новых версиях?
Какова политика в отношении устаревших функций (deprecated)?
Как долго поддерживаются старые версии?
Пример требования:
Новые версии АРИ публикуются каждый месяц (1-го числа в полдень), содержание релиза доступно за две недели до релиза через е-мейл рассылку; предупреждение об изменении контракта доступно за месяц до релиза.
Время отклика, объем данных, SLA, доступность.
Как обрабатываются ошибки (есть ли retry, fallback)?
Пример требования:Сервис должен быть доступен 24/7 с минимальным уровнем доступности 99.5%.
Совет: аналитик должен позаботиться, чтобы все технические параметры были выражены на языке требований, а не только документации, то есть описаны как синтаксические (к данным) так и семантические требования (к бизнес-логике, то есть использование данных).
Пример требований "собственника"
Название: Публичный API для создания заказа
Цель: Предоставить партнерам возможность создавать заказы напрямую.
Функциональность:
Метод POST /api/v1/orders принимает данные о клиенте и товарах.
При успехе возвращает идентификатор заказа.
В случае ошибки возвращает код 400 или 422 с пояснениями.
Безопасность:
Доступ только с использованием токена авторизации.
Лимиты: не более 60 запросов в минуту на клиента.
Совместимость:
Старые версии API поддерживаются 6 месяцев после релиза новой.
Когда вы – потребитель чужого API
Быть потребителем (consumer) означает, что вы интегрируетесь с API, контролируемым другой стороной. Для аналитика это, прежде всего, о сборе и проверке информации, потому что вы не можете изменять API - только адаптироваться к нему.
Что нужно выяснить перед подготовкой требований к интеграции
Направление | Примеры вопросов |
Доступность | Есть ли тестовая среда (sandbox)? Как получить ключи доступа? |
Документация | Есть ли описание OpenAPI/Swagger? Как часто обновляется? |
Изменения | Как нас предупреждают об обновлении или изменениях в контракте (breaking changes)? |
Безопасность | Какой метод проверки аутентификации? Обновляются ли токены автоматически?? |
Ограничения | Какие лимиты запросов или временные окна действия токенов? |
Ошибки | Как выглядит структура ответа при ошибке? Есть ли унифицированные коды ошибок? |
Поддержка | Есть ли единный контакт для технических вопросов или инцидентов? |
Советы аналитику-потребителю
Всегда храните копию документации. Уточните, актуальна ли она. В крупных компаниях бывают "мертвые" страницы.
Проверьте формат ошибок. Это часто мелочь, влияющая на всю интеграцию.
Например, API может возвращать "error": "Invalid token" или "message": "Auth failed" – и ваша логика обработки должна это учитывать.
Узнайте частоту обновлений. Если API меняется ежемесячно – предусмотрите механизм адаптации.
Спросите о SLA. Это поможет определить, как ваша система будет вести себя во время недоступности API.
Приметр требований “потребителя”
Название: Интеграция с внешним сервисом доставки
Описание:
API стороннего сервиса позволяет создавать заявки на доставку.
Метод POST /api/v1/shipments принимает данные об отправителе и получателе.
При временной ошибке (5xx) система должна выполнить повторный вызов до 3 раз с интервалом 15 секунд.
Зависимости:
Необходимо обновлять токен доступа каждый час через /auth/refresh.
Максимум 100 запросов в минуту.
Как аналитику поддерживать актуальность API-контрактов
API – это живой организм. Со временем появляются новые поля, версии, партнеры. Задача аналитика – сделать изменения прозрачными и управляемыми.
Документируйте изменения
Введите лог изменений (changelog) – краткий журнал изменений контракта: новые поля, изменения поведения, удаление.
Уточняйте, какие изменения обратно совместимы (backward compatible), а какие нет.
Пример требования: Все изменения в контракте (breaking changes) публикуются в логе изменений (changelog) не менее чем за 30 дней до релиза.
Договоритесь о политике версий:
Следует согласовать с технической командой:
как обозначаются версии (v1, v2, v1.1);
как долго поддерживается каждая версия;
когда старая версия считается устаревшей (deprecated).
Пример требования: Сервис поддерживает две основные версии API. Каждая версия активна не менее 12 месяцев после релиза новой.
Держите требования в общем репозитории
Идеальный вариант – иметь общее пространство (Confluence, Notion, SharePoint, Git), где:
аналитики, разработчики и тестировщики видят актуальную спецификацию;
можно отслеживать историю правок;
легко проверить, соответствуют ли тест-кейсы действующей версии контракта.
Совет: даже если техническая документация сохраняется отдельно, следует указать ссылку на конкретную версию API-документации.
Взаимодействие с тестированием API
Аналитик не тестирует API напрямую, но описывает ожидаемое поведение, которое ложится в основу тестов.
С этим помогает:
предоставление примеров запросов и ответов в требованиях;
согласование кодов ошибок;
описание предельных сценариев (“что будет, если поле пустое/ID несуществующий/токен недействителен”).
Чеклист для бизнес-аналитика для требований к API
Перед публикацией или интеграцией API задайте себе вопросы:
Категория | Проверка |
Функциональность | Ясно ли описано, какие действия доступны через API? |
Безопасность | Определен ли способ аутентификации? |
Совместимость | Описано ли, как ведет себя API после обновления? |
Надежность | Определены ли SLA, таймауты, лимиты? |
Коммуникация | Известно ли, как сообщают об изменениях? |
Тестирование | Есть ли примеры запросов/ответов для тестов? |
Вывод
Хороший API – это не только техническая реализация, а результат совместной работы команд. Бизнес-аналитик здесь – как координатор ожиданий: помогает сделать контракт понятным, требования – полными, а изменения – управляемыми.
В результате выиграют все:
разработчики – потому что имеют четкое описание;
тестировщики – потому что знают, что и как проверять;
партнеры и пользователи – потому что интеграции работают стабильно.
Если вы хотите углубить свои технические знания, обратите внимание на тренинги Technical skillsfor Business Analyst та Advanced Technical skills for Business Analyst
Новости и статьи по бизнес-анализу: