Що формується автоматично
UBC Data Bridge формує технічну HTML-довідку для точки API з її збережених налаштувань. Вона описує конкретну адресу, формат даних, поля, правила перевірки, параметри, відповіді й чинні ліміти. Це допомагає автору потоку та інтегратору працювати з одним контрактом, коли змінюється схема чи спосіб запуску.
Для приймання приклади враховують формат тіла або файлів, тестові дані, обов’язкові поля й унікальні ключі. Для видачі — режим збереженого результату чи запуску на запит, формат відповіді, фільтри та сторінки. Довідка показує стан точки: збереження чернетки не означає, що відповідні зміни вже працюють у Production.
1. Підготуйте контракт точки
- Назвіть підключення й потік так, щоб партнер розумів призначення набору, наприклад «Залишки магазинів — тест».
- Завершіть налаштування адреси та формату. Для приймання введіть невеликий коректний приклад, оновіть поля й перевірте типи, обов’язковість і ключі.
- Для видачі з’єднайте потрібний результат, задайте режим запуску й опишіть параметри зрозумілими словами. Перевірте, які з них обов’язкові.
- Збережіть налаштування підключення та блоку. Виконайте перегляд і симуляцію, виправте помилки, опублікуйте погоджену версію потоку.
- Відкрийте довідку повторно після змін. Звірте адресу, стан Production і приклад відповіді з тим, що має використовувати клієнт.
2. Відкрийте довідку й надайте доступ
Скористайтеся посиланням «Технічна документація» у властивостях API-блоку або у збереженому підключенні видачі. Каталог «API → Документація» показує доступні точки. Довідка блоку має маршрут /api/flows/{flow}/blocks/{node}/api-docs, точки видачі — /api/connections/{connection}/api-docs, каталогу — /api/api-docs. До них додається префікс установки.
Для відкриття потрібен вхід користувача в Data Bridge. Право має редактор потоку або користувач із правом ролі «API-документація», який бачить цей потік. Сам API-ключ не відкриває HTML-довідку. Увімкнення публічної видачі даних також не робить довідку загальнодоступною. Надайте інтегратору потрібний обліковий доступ, а ключ запитів передайте окремо.
3. Налаштуйте клієнт за прикладами
Почніть із «Швидкого старту»: скопіюйте адресу й налаштуйте Postman або curl. Довідка містить приклади Python та пояснення автентифікації. Якщо відповідні API-клієнти вимагають HMAC, показується сценарій підписання; використовуйте налаштування саме вашого ключа. Кнопки «Копіювати» біля адрес і коду допомагають перенести приклад без ручного переписування.
Підставте тестові значення й власний ключ у локальному захищеному середовищі. Довідка не містить секретів клієнтів. Для JSON збережіть точну структуру й шлях до масиву; для CSV — роздільник і заголовки; для файлів — спосіб передачі та ім’я. Не замінюйте формат запиту форматом, у якому автор ввів мок: це незалежні налаштування.
4. Перевірте успіх і очікувані відмови
Для приймання виконайте невеликий коректний запит, дочекайтеся завершення доставки та звірте результат отримувача. Потім перевірте відсутнє обов’язкове поле, неправильний тип, повтор унікального ключа й повтор доставки з тим самим Idempotency-Key. Помилка повинна бути зрозумілою клієнту, а повтор не повинен створювати зайвий запуск.
Для видачі перевірте першу й наступну сторінку, обов’язковий фільтр, порожній відбір і застарілі дані. У режимі запуску дочекайтеся відповіді за next із закріпленим run.id. Окремо перевірте недійсний ключ, заборонений потік і ліміт частоти. Фіксуйте HTTP-статус, код помилки, доставку/запуск і очікувану кількість рядків.
5. Підтримуйте контракт у роботі
Зіставляйте невдалий запит із «Налаштування → API → Аудит запитів» або «Запити API» у меню блоку. Перевіряйте метод, напрям, статус, тривалість і відповідь. Запис тіл залежить від налаштувань аудиту: вони можуть містити бізнес-дані, тому вибирайте потрібний обсяг і строк зберігання.
Таблиця лімітів довідки показує чинні значення: розмір запиту, чергу, очікування, сторінку та інші параметри відповідної точки. Після зміни лімітів відкрийте її заново. Після завершення доставки її вхідні дані очищаються; історія запусків і аудит мають власні правила зберігання. Якщо змінюється контракт партнерів, використайте нову версію адреси та погодьте перехід, зберігши стару на час міграції.