Що варто знати про вимоги до інтеграцій: роль бізнес-аналітика, коли ви - власник або споживач API - частина 2
- Ganna Kaplun
- 2 дні тому
- Читати 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
Новини та статті з бізнес-аналізу:
Коментарі