HTTP Request (full version)

Що таке HTTP Request

Блок HTTP Request — це універсальний інструмент DEV-платформи ApiX-Drive для взаємодії з будь-якими зовнішніми API. Він дозволяє виконувати HTTP-запити (GET, POST, PUT, PATCH, DELETE), передавати дані, отримувати відповіді сервісів і використовувати їх у подальшій логіці інтеграції.

HTTP Request є базовим будівельним блоком інтеграцій і використовується для реалізації кастомних сценаріїв, роботи з нестандартними API, побудови ланцюжків запитів, обробки помилок і валідації акаунтів.

Навігація

1. Коли і навіщо використовувати HTTP Request?
2. Де можна використовувати HTTP Request?
3. Як працює HTTP Request (логіка виконання)?
   3.1. Послідовність виконання
   3.2. Що є Результатом Виконання HTTP Request?
   3.3. Як HTTP Request впливає на потік флоу?
4. Основні налаштування HTTP Request.
   4.1. Settings
   4.2. Headers — HTTP-заголовки
   4.3. Body — тіло HTTP-запиту
   4.4. Note
   4.5. Execution Log — Результат Виконання
5. Робота з відповіддю API.
6. Обробка помилок (Request Error). Якщо HTTP Request завершується помилкою?
7. Приклади використання та комбінація з іншими блоками
   7.1. Умовна логіка на основі відповіді. HTTP + IF
   7.2. Підготовка та трансформація даних. HTTP + Object Builder
   7.3. Робота з масивами. HTTP + Loop: Object/List + Object Builder
   7.4. Валідація акаунту. HTTP + IF + Set Validation Result
   7.5. Передача результату. HTTP + Add Result to Output
   

Типові помилки

1. Використання неправильного методу запиту.
2. Невірна структура Body
3. Відсутні або некоректні Headers
4. Відсутність перевірки даних у відповіді
5. Відсутність Error Flow

FAQ

1. Де подивитися Результат Виконання HTTP-запиту?
2. Чому HTTP Request не виконується або повертає порожню відповідь?
3. Як передати дані з HTTP Request в інші блоки?
4. Чому API повертає 200 OK, але дані некоректні?
5. Як працює Parse Body і коли його використовувати?
6. Чи можна використовувати змінні та функції в HTTP Request?
7. Чи можна виконати HTTP Request умовно?
8. Що робити, якщо API працює нестабільно?

Коли і навіщо використовувати HTTP Request

─────────────────────────────────────────────────────────────-

• потрібно інтегрувати сервіс, якого немає серед готових конекторів;
• необхідно викликати кастомний endpoint API;
• потрібно змінити поведінку стандартного API-виклику;
• потрібно зробити декілька послідовних, залежних або умовних запитів;
• якщо API повертає складну або динамічну структуру відповіді і потрібно її обробити;
• необхідно працювати з токенами, підписами або кастомною авторизацією.

Де можна використовувати HTTP Request

─────────────────────────────────────────────────────────────-

Блок HTTP Request можна знайти в таких флоу:
Input, Main Action, Output, Account Validation, Request Error, Custom.

Це дозволяє виконувати HTTP-запити на будь-якому етапі інтеграції — від отримання вхідних даних до обробки помилок і перевірки валідності акаунту.

Для того щоб додати новий блок, натисніть на + та оберіть HTTP Request.

Розташування HTTP Request в флоу Main Action

Як працює HTTP Request (логіка виконання)

─────────────────────────────────────────────────────────────-

Послідовність виконання

1. Формується HTTP-запит на основі налаштувань блоку
2. Запит відправляється до зовнішнього API
3. Очікується відповідь сервера
4. Отримується HTTP-статус та тіло відповіді
5. Результат зберігається та стає доступним у флоу

Що є Результатом Виконання HTTP Request?

• HTTP-статус відповіді;
• тіло відповіді (body);
• заголовки відповіді (headers, якщо потрібно).

Ці дані можуть бути використані в наступних блоках, наприклад в IF, Object Builder, Loop або Add Output тощо.

Як HTTP Request впливає на потік флоу?

Якщо HTTP Request завершується успішно, флоу продовжує виконання наступного блоку.

У разі помилки або нестандартної відповіді логіка обробки може бути реалізована через Request Error, якщо в налаштуваннях запиту це обрано в полі Error Flow. 

Основні налаштування HTTP Request

─────────────────────────────────────────────────────────────-

Settings

У вкладці Settings задаються ключові параметри HTTP-запиту та його поведінка під час виконання.


URL

Кінцева точка (endpoint) зовнішнього API, до якої надсилається запит (наприклад, https://api.olostep.com/v1/scrapes).

Може бути статичною або динамічною (через змінні та режим EXP)


Method

HTTP-метод запиту:

• GET — отримання даних
• POST — створення або передача даних
• PUT / PATCH — оновлення
• DELETE — видалення

Обирайте метод відповідно до вимог API (наприклад, POST для створення ресурсів)  


Query Params


Parse Body

Визначає, у якому форматі слід розпарсити (перетворити) тіло відповіді від API. Зазвичай це JSON, оскільки більшість сучасних API повертають дані у цьому форматі.

JSON — відповідь буде автоматично розпарсена в об’єкт;

Нічого не обрано - відповідь буде текстова в тому форматі як її віддає система по API (в "сирому" вигляді). В цьому випадку дані не будуть доступні у Flow як змінні.

Store as File - для роботи з файлами.


Cache Time (0–300 sec)

Час, протягом якого результат цього запиту буде кешуватися в системі. Якщо запит повториться до закінчення цього часу, буде використано кешовану відповідь.

0 — кешування вимкнено;
>0 — встановлюйте тільки для статичних або рідко оновлюваних даних для зменшення навантаження на API та прискорення Flow(списки, моделі, тощо).


Connection Timeout (1–60 sec)

Максимальний час очікування встановлення з’єднання з сервером.

За замовчуванням - 30 секунд.

Зазвичай 30 секунд є достатнім. Збільшуйте лише для віддалених або повільних серверів.


Response Timeout (5–300 sec)

Максимальний час очікування отримання повної відповіді від сервера після встановлення з'єднання.

За замовчуванням - 60 секунд. 

Корисно для повільних API або операцій типу експорту / парсингу.


Error Flow

Вибір окремого, заздалегідь налаштованого Flow для обробки помилок HTTP-запиту.

Якщо запит повертає помилку (4xx / 5xx), виконання переходить у вказаний Error Flow, де можна:

• проаналізувати відповідь API та побудувати структуру помилок
• сформувати зрозумілу помилку

Best practice: обов'язково підключайте Error Flow для HTTP Request для обробки помилок.


Response

Цей розділ відображає результат виконання HTTP-запиту без переходу до Execution Log. Він дозволяє швидко перевірити, чи коректно сформований запит і яку відповідь повертає API, ще на етапі налаштування блоку.

Після виконання запиту у блоці HTTP Request в Response можна побачити:

• HTTP-статус відповіді (наприклад, 200, 400, 401, 500)
• тіло відповіді API (response body)
• помилку або повідомлення сервера, якщо запит завершився невдало

Дані відображаються у «сирому» вигляді або у форматі, визначеному параметром Parse Body.

Headers — HTTP-заголовки

У вкладці Headers задаються HTTP-заголовки запиту. Ними можна керувати передачу типу контенту, авторизації, передачу службових необхідних параметрів.

Типові заголовки:

• Authorization
• Content-Type
• Accept
• кастомні headers API

Значення можуть бути:

• статичними
• динамічними (через змінні, в режимі EXP, через Object Builder)

Приклад:

Authorization: Bearer {{ACCOUNT.token}}

Content-Type: application/json

Body — тіло HTTP-запиту

У вкладці Body налаштовується тіло запиту. Тип тіла залежить від вимог API.

Важливо: в залежності від того, який ви обираєте тип body, на вкладці HEADERS автоматично змінюється заголовок "Content-type".  

Доступні типи Body

URL-Encoded Params

Це формат передачі даних у тілі HTTP-запиту у вигляді пар "ключ=значення",  закодованих за стандартом application/x-www-form-urlencoded.

Використовуйте, якщо :

• API прямо цього вимагає;

• ви працюєте зі старим або обмеженим сервісом;

• у документації API зазначено x-www-form-urlencoded;

• потрібно передати прості ключ–значення без вкладень.

Формат запиту: В розділі Execution Log ви побачите фактичний формат запиту який був відправлений.


JSON-Encoded Params

Структурований формат, де дані вводяться як пари "ключ-значення", а система автоматично перетворює їх на валідний JSON-рядок.

Переважно використовується для невеликих, фіксованих JSON-об'єктів.

Формат запиту: В розділі Execution Log ви побачите фактичний формат запиту який був відправлений.


Raw text data

Відправка тіла запиту як звичайного, неструктурованого тексту, наприклад: Log-файлів, текстових нотаток або інших довільних даних, що не є JSON/формами. 
Жоден символ не змінюється, не додається і не видаляється.

Навіть якщо вставити JSON як текст, відправиться він як текст, а не як JSON-обʼєкт і не буде оброблений, виникне помилка

Формат запиту: В розділі Execution Log хоч ви і побачите прописаний JSON, але це звичайний текст, і система у відповіді скоріше за все поверне помилку.


Raw JSON data

Дозволяє ввести "сирий" JSON.

Використовується для складних, вкладених JSON-структур, які незручно формувати через параметри.
Зручно коли JSON уже сформований в Object Builder або приходить з іншого блоку.

В даному прикладі ми сформували в Object Builder формат запиту, і зберегли в Глобальну змінну request, і цю змінну ми будемо використовувати, додатково застосувавши для змінної навісну функцію (декоратор) Encode object as JSON 

Формат запиту: В розділі Execution Log ви побачите фактичний формат запиту який був відправлений.  


File by ID

Використовується для передачі файлів (зображень, документів, тощо), отриманих у попередніх блоках флоу (ідентифікується за ID).


Multipart / Related

Відправка файлів у поєднанні з додатковими полями форми (наприклад, завантажити фото і вказати його опис).

Note

Вкладка Note дозволяє залишити коментар до блоку:

• опис логіки запиту
• посилання на документацію API
• пояснення нестандартних рішень

Не впливає на виконання, але критично корисна для підтримки та командної роботи.

Execution Log — Результат Виконання

Вкладка Execution Log  є ключовим інструментом для тестування та відладки. Вона відображає результати фактичного виконання HTTP-запиту.


REQUEST

Фактичний запит, який був надісланий на зовнішній API (включаючи URL, метод, заголовки та тіло запиту(body)).


RESPONSE

Відповідь, отримана від зовнішнього API серверу, включаючи HTTP-статус (наприклад, 200, 402) та сире тіло відповіді.  


Execution Results

Розпарсений результат відповіді (якщо Parse Body = JSON) готовий для використання в наступних кроках Flow. Саме ці дані використовуються далі у подальшій логіці.


Errors

Якщо підключений та налаштований Error Flow, тут будуть показані помилки, якщо запит був неуспішний.

Робота з відповіддю API

─────────────────────────────────────────────────────────────-

Після успішного відправлення HTTP-запиту, блок HTTP Request отримує відповідь від зовнішнього сервера. Правильна обробка цієї відповіді (Response) забезпечує надійність вашого Flow і дозволяє коректно використовувати отримані дані.  


1. Аналіз HTTP Status Code

Першим і найважливішим етапом є аналіз HTTP Status Code (код стану), який визначає загальний результат запиту. Цей код доступний у вкладці Execution Log та є основою для подальшої логіки:

• 2xx (Успіх): Запит був успішно отриманий, зрозумілий та прийнятий.
  Наприклад: 200 OK (загальний успіх), 201 Created (ресурс створено). Це дозволяє перейти до використання отриманих даних.
• 4xx (Помилка клієнта): Проблема виникла через некоректний запит (наприклад, помилкові дані, недійсна авторизація). Активується Error Flow (треба попередньо налаштувати Request Error).
  Наприклад: 400 Bad Request, 401 Unauthorized, 404 Not Found.
• 5xx (Помилка сервера): Проблема виникла на стороні API-сервера. Активується Error Flow (треба попередньо налаштувати Request Error).
  Наприклад: 500 Internal Server Error, 503 Service Unavailable


2. Парсинг відповіді (Parse Body)

Якщо в налаштуваннях HTTP Request обрано Parse Body, тіло відповіді автоматично розбирається у структурований формат JSON.

У результаті:

• всі поля відповіді стають доступними як змінні;
• вкладені об’єкти та масиви зберігають структуру;
• дані відображаються у Execution Results.

Якщо Parse Body вимкнено — відповідь доступна лише як сирий текст і не може використовуватись у логіці Flow.


3. Використання даних у подальшій структурі Flow

Розпарсена відповідь HTTP Request може бути передана в інші блоки Flow:

• IF — для перевірки значень, статусів або умов;
• Loop — для обробки масивів;
• Object Builder — для формування нової структури даних;
• Add Output / Next HTTP Request — для передачі даних далі по сценарію.

Таким чином, HTTP Request виступає джерелом даних для всієї подальшої логіки Flow.


4. Обробка Нестандартних Відповідей

Деякі API повертають завжди статус - 200 OK, навіть якщо сталася логічна помилка.

Наприклад,  ви отримали 200 OK, але в JSON є поле "status": "error", саме по цьому полю ви можете обробити помилки в Error Flow, тобто вказати умову: Якщо статус == "200" , а також && чи існує ISSET() поле "status": "error" . В цьому випадку це і буде правильна обробка помилки.

Тож не бажано покладатись лише на код статусу відповіді, треба умову комбінувати з наявністю інших полів.


5. Обробка Помилок (Error Flow)

Request Error напряму пов'язаний з блоком HTTP Request, саме тому в налаштуваннях Error Flow ви можете обрати флоу в якому ви налаштували структуру обробки необхідних помилок.

Обробка помилок (Request Error). Якщо HTTP Request завершується помилкою?

─────────────────────────────────────────────────────────────-

Якщо HTTP Request завершується помилкою (4xx, 5xx або некоректна відповідь), сценарій переходить у флоу Request Error.

Request Error - це окремий, ізольований потік логіки, який виконується автоматично, коли HTTP-запит не повертає успішний статус. 

В Request Error доступні:

• HTTP Status Code;
• тіло відповіді (якщо воно було повернене);
• технічна інформація про помилку (timeout, connection error);
• headers відповіді (якщо вони були отримані).

Для кожного блоку HTTP Request можна обрати один спільний Error Flow або окремо налаштований, якщо структура в них різна.

Якщо в блоці HTTP у вас обраний Error Flow, то під час запиту, в Лозі, додається структура Request Error, де можна побачити як саме відпрацював цей потік логіки, та при наявності помилок вони будуть відображені.

Приблизно так може виглядати структура Request Error

В Лозі це виглядатиме так

Приклади використання та комбінація з іншими блоками

─────────────────────────────────────────────────────────────-

Блок HTTP Request можна комбінувати з різними блоками, зазвичай використовується разом з IF, Object Builder, Output та Loop для побудови гнучкої логіки інтеграції.

• Умовна логіка на основі відповіді. HTTP + IF

Блок IF використовується як перед, так і після блоку HTTP Request для керування логікою виконання флоу і визначає: чи виконувати HTTP-запит, як обробляти його результат, по якій гілці сценарію продовжиться виконання флоу.

Перед HTTP Request , IF дозволяє:

• перевірити вхідні дані перед відправкою запиту;
• переконатися, що обов’язкові поля заповнені;
• вирішити, чи потрібно виконувати HTTP-запит взагалі, або пропустити його.

Після HTTP Request , IF використовується для:

• перевірки результату запиту;
• аналізу значень у відповіді API;
• розгалуження сценарію залежно від отриманих даних або статусу.

В нашому прикладі виконується перший запит на створення сутності, після чого ми перевіряємо чи існує userId з блоку HTTP, тобто чи була створена сутність, якщо існує, то ми йдемо по гілці True, і проводимо додаткові перевірки на наявність чи заповненість полів, включаючи проходження циклом, і в залежності від результату виконання цих блоків ми вирішуємо чи робити ще один запит на додавання тега до сутності.

• Підготовка та трансформація даних. HTTP + Object Builder

Блок Object Builder використовується разом з HTTP Request для підготовки та трансформації даних до або після виконання запиту.

Перед HTTP Request, Object Builder дозволяє:

• сформувати тіло запиту відповідно до вимог API;
• змінити структуру даних;
• привести типи значень (string, number, boolean);
• обʼєднати або доповнити обʼєкти перед відправкою.

Після HTTP Request, Object Builder використовується для:

• підготовки даних для подальших блоків або Output;
• формування єдиного обʼєкта незалежно від структури відповіді.

В даному прикладі ми сформуємо тіло запиту як того вимагає API. Нам треба отримати такий формат:

{"messages":[{"role":"user","content":"How are you?"}],"model":"grok-2-vision-1212","max_completion_tokens":1024,"temperature":1,"frequency_penalty":1,"presence_penalty":1,"n":1}

Для формування масива messages ми можемо використати лайфхак. В окремому Object Builder сформувати внутрішні значення властивості

Після цього в новому Object Builder , де будемо формувати основний запит, ми вкажемо дію для ключа messages Set Ptoperty Object , і вкажемо що key це - 0 , а значення це - Результат виконання нашого попереднього блоку, таким чином ми отримаємо масив. 

Для інших полів просто виконуємо перевірку на заповненість, і якщо значення не пусте, тоді додамо в запит

В HTTP ви отримаєте саме той формат запиту, який треба

• Робота з масивами. HTTP + Loop: Object/List + Object Builder 

Блок Loop: Object/List може використовуватись разом з HTTP Request для обробки масивів, отриманих у відповіді API або підготовлених для відправки.

Loop: Object/List дозволяє:

• пройтися по масиву обʼєктів з відповіді API;
• зібрати пагінацію;
• відфільтрувати або зібрати дані в нову структуру.

В даному прикладі ми у флоу Input зробимо запит на отримання моделей по AI системі, пройдемося циклом Loop по масиву з моделями, і за допомогою Object Builder сформуємо динамічний список моделей та збережемо в Глобальну змінну.
Далі в блоці Add Input оберемо динамічний список і вставимо туди нашу Глобальну змінну в якій вже будуть всі моделі з HTTP запиту.

• Валідація акаунту. HTTP + IF + Set Validation Result

Звʼязка HTTP Request з блоком Set Validation Result використовується у флоу Account Validation для перевірки коректності підключення до зовнішнього сервісу.

HTTP Request виконує запит до API, а на основі відповіді визначається, чи пройшла авторизація успішно, а також перевіряється статус відповіді або наявність необхідних полів.

Блок Set Validation Result фіксує результат перевірки: 1 — акаунт валідний; 0 — валідація не пройдена.

В даному прикладі ми робимо запит до одного з методів API та отримуємо успішну відповідь, далі перевіряємо чи існує поле data у відповіді, якщо існує, то ідемо в гілку True і в блоці Set Validation Result статус ставимо 1. Якщо б поля такого у відповіді не існувало то ми пішли б у гілку False і статус був би 0.

• Передача результату. HTTP + Add Result to Output

Звʼязка HTTP Request з блоком Add Result to Output використовується для формування фінального результату інтеграції.

Дані з відповіді API:

• передаються напряму в Output або попередньо трансформуються через IF, Object Builder чи Loop;
• можуть виводитись у різному форматі залежно від результату запиту.

В даному прикладі ми після запиту відразу додаємо результат до виводу, де можна буде зробити імпорт у флоу Output щоб інформація відображалась користувачу.
В розділі Test ви побачите фактичні дані по останній відповіді.

Типові помилки

─────────────────────────────────────────────────────────────-

1. Використання неправильного методу запиту.

Приклад проблеми:

• API очікує POST, але використовується GET;
• API приймає PUT, але надсилається PATCH.


2. Невірна структура Body

API може повертати помилку, навіть якщо всі параметри передані, але у неправильному форматі.

Типові помилки:

• невірний JSON (відсутні дужки, лапки, коми);
• неправильний тип даних (рядок замість числа, масив замість обʼєкта);
• передача параметрів у Body замість Query Params або навпаки.


3. Відсутні або некоректні Headers

Без необхідних заголовків API може повертати 401 або 403 помилки.

Найчастіше забувають:

• Authorization;
• Content-Type;
• Accept.

Як уникнути:

• перевіряйте, які headers є обовʼязковими для API;
• не передавайте Content-Type, якщо API його не очікує.


4. Відсутність перевірки даних у відповіді

Навіть при успішному статусі API може повернути:

• порожній масив;
• null значення;
• часткові або неповні дані.

Як уникнути:

• перед використанням відповіді перевіряйте наявність полів;
• використовуйте IF для перевірки даних;
• не запускайте Loop для порожніх масивів.


5. Відсутність Error Flow

Без налаштованого Error Flow будь-яка помилка API може зупинити сценарій або призвести до некоректної логіки.

Як уникнути:

• завжди вказуйте Error Flow для HTTP Request;
• обробляйте помилки окремо від основної логіки в Request Error.

FAQ

─────────────────────────────────────────────────────────────-

Де подивитися Результат Виконання HTTP-запиту?

• у вкладці Execution Log блоку HTTP Request;
• у секції Response у вкладці Settings після натисканні Save або Send;
• у Лозі.

Там відображаються: фактичний запит (URL, headers, body), статус-код відповіді, сирий response, розпарсені дані (Execution Results).

Чому HTTP Request не виконується або повертає порожню відповідь?

• неправильний HTTP-метод;
• некоректний URL або endpoint;
• відсутні обовʼязкові headers (наприклад, Authorization);
• неправильна структура Body;
• API повертає пусту відповідь.

Рекомендуємо перевірити Execution Log і структуру відповіді.

Як передати дані з HTTP Request в інші блоки?

Після виконання запиту:

• всі розпарсені дані доступні як змінні у Flow;
• їх можна використовувати в IF, Object Builder, Loop, Add Output та інших блоках;
• доступ до даних здійснюється через структуру відповіді, отриману в Execution Results.

Чи можна використовувати змінні та функції в HTTP Request?

Так.
У HTTP Request можна використовувати:

• змінні з попередніх блоків;
• функції та оператори в режимі роботи поля - EXP;
• динамічні значення у URL, headers та body.

Що робити, якщо API працює нестабільно?

• використовуйте Error Flow для обробки;
• збільшуйте Timeout при необхідності;
• перевіряйте відповідь перед обробкою;
• тестуйте сценарій з різними відповідями API.