Что стоит знать о требованиях к интеграции: API как контракт (Ч. 1)
- Ganna Kaplun
- 13 окт.
- 5 мин. чтения
Когда мы говорим об интеграции систем, речь часто идет об обмене данными где-то под капотом. Интеграция – это договор между двумя сторонами, в котором каждая имеет свои обязательства. Если взаимодействие осуществляется через API, настоящий договор – API-контракт (API contract).
Все, что касается интеграций (как и создание любых систем), начинается не с кода, а с требований - как именно системы должны взаимодействовать, что передается, при каких условиях, и как реагировать, когда что-то идет не так.
Что такое API контракт
API-контракт – это не только описание формата запроса и ответа. Это набор правил и договоренностей, которые определяют, как две системы общаются между собой. Если провести аналогию с человеческим языком, то контракт – это не просто словарь (формат данных), но и грамматика, этикет и тон общения.
Основные состовляющие контратка:
Кінцеві точки (endpoints) - адреса, по которым можно вызывать функциональность, например :GET /api/v1/customers/{id}
POST /api/v1/orders
Методы (methods) - определяют тип действия : GET (получить), POST (создать), PUT (обновить), DELETE (удалить).
Тела запросов и ответов (request/response bodies) - структура сообщений, например, в формате JSON або XML.
Статус-коды (status codes) - как система отвечает на результат: 200 OK, 400 Bad Request, 500 Internal Server Error.
Заголовки (headers) - дополнительная служебная информация.
системные (например, Content-Type, Authorization);
пользовательские, или несистемные - могут передавать идентификатор транзакцыии, язык интерфейса, часовой пояс, версию клиента и т.д.
Пример: X-Client-Version: 2.1.0, X-Request-ID: a12f9d0e-5678-42aa-bc1f-08d3f9c12234
Метод аутентификации/авторизации (authentication/authorization) - как пользователь доказывает, что он имеет право вызывать API:
API ключ (API key)
маркер доступа (token)
OAuth 2.0
базовая аутентификация (Basic Auth)
Правила версионирования (versioning) - например, через URL (/v1/...) или заголовки (Accept: application/vnd.company.v2+json).
Контракт - это больше чем формат сообщения
Представим, что одна система отправляет запрос на на создания заказа:
POST /api/v1/orders
{
"customerId": 125,
"items": [
{"productId": "A123", "quantity": 2}
]
}
Если ответ API просто возвращает 200 OK, то для потребителя это может быть “успех”, но без деталей. Хорошо спроектированный контракт определяет, какой ответ ожидает другая сторона, например:
{
"orderId": "ORD-2025-0012",
"status": "created",
"estimatedDelivery": "2025-10-15"
}
Контракт описывает не только структуру, но и ожидаемое поведение, ограничения и исключения.
Советы для аналитика:
если вы видите описание API только в виде примера сообщения в случае успеха - спросите другие аспекты контракта: аутентификацию, ограничения запросов, коды ошибок, требования к параметрам (обязательность, ограничения на минимум-максимум и точность для чисел, разрешенные символы и длина для строк и т.п.);
следует помнить, что в дальнейшем данные будут использоваться в аппликации, например, записываться и читаться из базы данных, и типы данных в JSON или XML скорее всего не будут в точности совпадать: чем больше вы узнаете на этапе интеграции о контракте, тем легче будет этот процесс в будущем.
Нефункциональные требования к API
В контексте интеграций нефункциональные требования часто имеют не меньшее значение, чем функциональные.
Продуктивность (performance):
среднее время отклика (response time);
ограничение на количество запросов в минуту (rate limiting);
допустимые объемы данных в запросе/ответе.
Пример требования :API должно обробатывать не менее 100 запросов в секунду со средним временим ответа до 500 мс.
Надежность и доступность(reliability & availability):
поддерживается ли повтор вызова в случае сбоя;
SLA (уровень доступности, например, 99.9% uptime);
поведение во время временных ошибок.
Пример требования: Уровень доступности должен быть пять девяток (99.999% времени АРІ должен быть доступным).
Безопасность:
шифрование трафика (TLS/HTTPS);
защита токенов;
политика доступа по ролям (role-based access).
Пример требования: АРИ доступны пользователям с валидным токеном, однако, вызовы POST, PUT, DELETE - только тем, которые имеют право изменять данные.
Мониторинг и логирование:
ведется ли адут вызовов;
можно ли идентифицировать источник каждого запроса(X-Request-ID).
Совместимость и версионирование:
backward compatibility (обратная совместимость) - старые клиеты не должны “сломаться” после обновления API;
политика предупреждения о breaking changes.
Пример требования:API должно поддерживать две последние основные версии. О несовместимых изменениях (breaking changes) следует сообщать не позднее чем за 30 дней.
Другие форматы обмена сообщениями
REST API – не единственный способ интеграции. Требования изменяются в зависимости от технологии.
Webhooks
Это "обратные вызовы": система-источник посылает сообщение системе-потребителю, когда происходит определенное событие.
На что обратить внимание в требованиях:
как часто могут поступать сообщения;
как система должна реагировать на дубликаты;
есть ли повторная попытка при ошибке (retry policy);
аутентификация отправителя.
Пример требования: Система должна повторно передавать webhook в случае получения ответа 5xx до трех раз с интервалом 10 секунд.
Веб-сокеты (Web Sockets)
Используются для обмена сообщениями в режиме реального времени – например, в чатах или мониторинговых панелях.
Важно уточнить:
нужен ли постоянный канал связи;
как восстанавливается соединение после разрыва;
передается ли аутентификация в каждом сообщении.
Пример требования: При потере соединения клиент должен автоматически подключаться в течение 5 секунд.
Очереди сообщений(Message Queues)
Подходят для асинхронных обменов, когда мгновенный ответ не требуется. Примеры технологий: RabbitMQ, Kafka.
В требованиях важно указать:
гарантии доставки (одно сообщение - exactly-once, как минимум одно сообщение - at-least-once);
максимальный размер очереди;
политику повторов при сбое.
Как формулировать требования к контркту
При сборе требований к интеграции задайте вопросы, которые выходят за пределы “что именно передается”.
Направление | Пример вопроса |
Безопасность | Какой метод проверки подлинности используется? Как обновляются токены? |
Надежность | Что делает система при ошибке 5xx? Есть ли retry policy? |
Совместимость | Как часто обновляется API? Поддерживается ли обратная совместимость? |
Тестирование | Доступна ли sandbox-среда для интеграций? |
Логирование | Как отследить проблемный запрос в логах? Есть ли корреляционный ID? |
Ремарка: Даже если аналитик не создает Swagger-документацию, безусловно, стоит знать, что там должно быть. Контракт – это не только технический документ, это часть требований, которую нужно согласовать с обеих сторон.
Пример формулирования требования
Название: Требования к вызову сервиса создания заказа
Описание:
● Сервис доступен по методу POST /api/v1/orders.
● Формат запроса - JSON, поля customerId и items - строки и являются обязательными .
● В случае ошибки возвращается код 400 с описание в поле errorMessage.
● Аутентификация – токен в заголовке Authorization.
● Максимум 10 запросов в минуту от одного клиента.
● Сервис должен отвечать в течение ≤ 500 мс.
● Все вызовы логируются со значением X-Request-ID.
Итоги
Контракт API - это договор, а не только техническая спецификация. Хорошо прописанные требования к интеграции:
● помогают избежать "языковых барьеров" между командами;
● упрощают тестирование и поддержку;
● делают развитие системы системы прогнозируемым.
Во второй части рассмотрим:
● как формулировать требования, когда вы собственник API;
● как собирать правильные вопросы, когда вы потребитель чужого API;
● и как обеспечить управляемость изменениями (версии, совместимость, логирование изменений - changelog).
Если вы хотите углубить свои технические знания, обратите внимание на тренинги Technical skillsfor Business Analyst та Advanced Technical skills for Business Analyst
Новости и статьи по бизнес-анализу:
Комментарии