Що варто знати про вимоги до інтеграцій: API як контракт (Ч. 1)
- Ganna Kaplun
- 9 годин тому
- Читати 5 хв
Коли ми говоримо про інтеграцію систем, мова часто йде про обмін даними десь “під капотом”. Інтеграція - це договір між двома сторонами, у якому кожна має свої зобов’язання. Якщо взаємодія здійснюється через АРІ, цей договір - 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
Новини та статті з бізнес-аналізу:
Коментарі