Інтеграція Retool з REST та GraphQL API: налаштування під ключ

Інтеграція Retool з REST та GraphQL API: налаштування під ключ

При розробці внутрішнього інструменту на Retool часто стикаються з тим, що REST або GraphQL API повертає дані в незручному форматі, а прямий доступ до бази даних заборонено. Наприклад, дати приходять в ISO, статуси — числами, а пагінація потребує ручної обробки. Ми допомагаємо налаштувати інтеграцію так, щоб дані приходили вже підготовленими для таблиць і форм. Підтримуємо будь-які REST та GraphQL API, а також SOAP та gRPC через кастомні ресурси. У цій статті розберемо, як правильно підключити API, налаштувати запити та трансформації, а також порівняємо REST і GraphQL.

Які API можна підключити до Retool?

Retool підтримує будь-які REST та GraphQL API, а також SOAP, gRPC та інші протоколи через кастомні ресурси. Можна підключати як публічні сервіси (Slack, Stripe), так і внутрішні мікросервіси. Головне — щоб був доступний ендпоінт і підтримувалася аутентифікація. Типові сценарії: підключення CRM, білінгу, аналітики. Ми реалізували інтеграцію для проекту з 15 мікросервісами — час завантаження дашборду скоротився на 40%.

REST API: налаштування ресурсу та запити

У Retool → Resources → REST API створюємо ресурс з базовим URL та заголовками:

Base URL: https://api.example.com/v1
Headers:
  Authorization: Bearer {{ retoolContext.userInfo.email }}
  Content-Type: application/json
  X-Service: retool-internal

Для динамічного токена використовуємо Custom Auth з OAuth2 або запит токена через окремий query. Приклади типових запитів:

// Query: getUsers (GET з фільтрацією та пагінацією)
{
  "method": "GET",
  "path": "/users",
  "queryParams": {
    "search": "{{ searchInput.value }}",
    "status": "{{ statusFilter.value }}",
    "page": "{{ currentPage.value }}",
    "limit": "20"
  }
}

// Query: updateUserStatus (PATCH з тілом)
{
  "method": "PATCH",
  "path": "/users/{{ usersTable.selectedRow.data.id }}",
  "body": {
    "status": "{{ newStatusSelect.value }}",
    "reason": "{{ reasonInput.value }}"
  }
}

Така конфігурація дозволяє перевикористовувати запити та уникнути дублювання.

GraphQL: особливості підключення та запитів

GraphQL потребує вказання ендпоінту (зазвичай /graphql) та може використовувати заголовки для токена. У Retool зручно передавати змінні через Variables:

# Query: fetchDashboardData
query GetDashboard($userId: ID!, $ordersLimit: Int!) {
  user(id: $userId) {
    id
    name
    email
    subscription { plan, status, expiresAt }
    orders(limit: $ordersLimit) {
      id
      status
      total
      createdAt
    }
  }
}

Variables у Retool:

{
  "userId": "{{ userIdInput.value }}",
  "ordersLimit": 10
}

Важливо: для складних схем типізація допомагає уникнути помилок на етапі розробки.

Чому важливі трансформери?

Дані з API рідко приходять у форматі, готовому для UI. Наприклад, дати в ISO потребують локалізації, статуси — перекладу. JavaScript-трансформери вирішують це:

// Transformer для форматування даних таблиці
return data.users.map(user => ({
  ...user,
  createdAt: new Date(user.createdAt).toLocaleDateString('uk-UA'),
  statusLabel: { active: 'Активний', blocked: 'Заблокований' }[user.status] || user.status,
  lifetimeValue: `${user.lifetimeValue.toLocaleString('uk-UA')} ₴`
}));

Трансформери виконуються на клієнті — це знижує навантаження на сервер. В одному з проектів ми обробляли до 1000 рядків за 200 мс.

Як порівнюються REST та GraphQL у Retool?

Висновок: REST швидше в налаштуванні, GraphQL ефективніше при складних зв'язках. Retool підтримує обидва — вибирайте під задачу.

Які типи аутентифікації підтримуються?

Що входить у нашу роботу з налаштування Retool?

Ми виконуємо інтеграцію під ключ, яка включає:

1. Аналіз — вивчаємо ваші API endpoints, схеми даних та вимоги до інтерфейсу.
2. Налаштування ресурсів — створюємо REST та GraphQL ресурси з коректною аутентифікацією (Bearer, OAuth2, API key).
3. Створення запитів — розробляємо 5–10 типових запитів з фільтрацією, пагінацією, мутаціями.
4. Трансформери — пишемо JavaScript-перетворення для форматування дат, статусів, обчислень.
5. Вебхуки — налаштовуємо Webhook-тригери для автоматизації (наприклад, відкриття профілю при тікеті в Zendesk).
6. Документація — передаємо опис усіх ресурсів, запитів та трансформерів.
7. Навчання — проводимо 1–2 сесії для вашої команди (опціонально).
8. Retool Workflows — автоматизація послідовностей дій для складних сценаріїв.

Скільки часу займає налаштування?

Підключення одного REST або GraphQL ресурсу та створення 5–10 запитів з трансформерами — від 1 до 2 днів. Для складних інтеграцій з декількома API та кастомною логікою — до 5 днів. Терміни уточнюємо після аналізу. Типова економія часу при використанні трансформерів — до 60% на обробці даних. Вартість інтеграції розраховується індивідуально та залежить від складності проекту.

Типові помилки та їх вирішення

• Ігнорування N+1 — при REST робіть один запит з вкладеними даними замість декількох.
• Витік токенів — ніколи не зберігайте секрети в коді додатку, використовуйте змінні оточення Retool.
• Складні трансформери — виносьте логіку на backend, якщо вона потребує доступу до БД або зовнішніх сервісів.
• Відсутність обробки помилок — додавайте перевірки статусу відповіді та fallback для користувача.

Ми гарантуємо, що після налаштування ваш Retool-інструмент буде стабільно працювати з будь-якими API. Наш досвід — понад 5 років на ринку, десятки проектів з інтеграції. Зв'яжіться з нами для оцінки вашого проекту — ми підберемо оптимальне рішення. Отримайте консультацію вже сьогодні, щоб прискорити розробку.

Розробка API: REST, GraphQL, WebSocket, tRPC

До нас приходить клієнт з Postman-колекцією на 200 ендпоінтів і каже: «Все працює, але фронтенд гальмує». Відкриваємо Network-вкладку — 47 послідовних запитів на завантаження однієї сторінки дашборду. Кожен чекає попереднього. Це не проблема швидкості сервера — це проблема архітектури API. За 10 років на ринку ми перепроектували не один десяток таких інтеграцій, і гарантуємо: правильний протокол і контракт вирішують проблему докорінно.

Коли REST перестає справлятися

REST добре працює для простих CRUD-операцій. Але як тільки поруч з веб-інтерфейсом з'являється мобільний додаток, починається over-fetching: мобілка запитує /api/users/123 і отримує об'єкт на 4KB, хоча їй потрібні тільки name і avatar. Помножте на список з 50 користувачів — 200KB трафіку замість 8KB.

GraphQL вирішує це через selection sets. Клієнт описує саме ті поля, які йому потрібні, і сервер повертає саме їх. На проекті з React Native + Next.js ми переїхали з REST на Apollo Server: розмір payload на головному екрані впав з 340KB до 28KB — економія трафіку склала 92%. Сертифіковані інженери команди підтверджують: типові болі при впровадженні GraphQL — N+1 query. Резолвер для поля author у поста викликає SELECT * FROM users WHERE id = ? для кожного поста у списку. На сторінці з 20 постами — 21 запит до бази. Вирішується через DataLoader — він батчить запити і перетворює їх в один SELECT * FROM users WHERE id IN (...).

Що таке tRPC і чим він кращий за REST/GraphQL?

Якщо весь стек на TypeScript (Next.js + Node/Bun), tRPC прибирає цілий шар проблем. Ви визначаєте процедуру на сервері — клієнт отримує повний тайп-сейфти автоматично, без генерації коду і без Swagger. Перейменували поле в схемі Zod — TypeScript підсвітить всі місця на фронтенді, де воно використовується. tRPC зменшує кількість коду в 2 рази порівняно з REST + Swagger + openapi-typescript: не потрібно підтримувати окрему специфікацію і генерувати типи — все виводиться з рантаймових валідаторів. Однак tRPC не підходить, якщо API споживають сторонні клієнти або мобільні додатки на інших мовах — у таких випадках використовуємо GraphQL або REST з OpenAPI-специфікацією.

WebSocket і реальний час: коли SSE, коли WS?

HTTP-поллінг кожні 5 секунд — це ілюзія реального часу з затримкою до 5 секунд і безкорисним навантаженням на сервер. Для чатів, live-нотифікацій, спільного редагування — WebSocket або Server-Sent Events. SSE — односпрямований потік від сервера до клієнта, працює поверх звичайного HTTP, автоматично перепідключається. Підходить для нотифікацій, стрімінгу даних, прогрес-барів. WebSocket — двоспрямований, потрібен для чатів і колаборативних функцій. Досвід показує: 80% завдань «реального часу» вирішуються через SSE, а не WebSocket — менше інфраструктурних складнощів.

Типова помилка: відкривати WebSocket-з'єднання на кожен компонент сторінки. На одному проекті дашборд відкривав 12 паралельних WS-з'єднань. Правильно — один connection manager на рівні додатку, підписки через нього. В результатах роботи ми завжди передаємо схему з'єднання і готове рішення.

Swagger / OpenAPI як контракт

Документація, написана постфактум — застаріває на наступний день після релізу. Ми пишемо специфікацію OpenAPI 3.1 до початку розробки, вона стає контрактом між фронтендом і бекендом. Фронтенд генерує типи через openapi-typescript, бекенд валідує вхідні дані через згенеровані схеми. Розбіжність контракту з реалізацією ловиться на CI, а не на рев'ю. Для Laravel — l5-swagger або dedoc/scramble. Для Node.js — @fastify/swagger або Zod + zod-to-openapi.

Як правильно аутентифікувати API?

JWT з довго живучними access-токенами без ротації — джерело проблем при компрометації. Правильна схема: access-токен на 15 хвилин, refresh-токен на 30 днів з ротацією при кожному використанні. Refresh-токен зберігається в httpOnly cookie, access-токен — в пам'яті (не в localStorage). Для міжсервісної взаємодії — API Keys з scope-обмеженнями або mTLS. OAuth 2.0 з PKCE для публічних клієнтів (SPA, мобілки).

Версіонування і зворотна сумісність

Ламаючі зміни в API без версіонування ламають клієнтів. Три підходи ми використовуємо в проектах:

Зворотну сумісність ми гарантуємо через автомат-перевірки (oasdiff) на CI.

Як ми розробляємо API: покроковий план

1. Аналітика — аудит поточних інтеграцій, складання схеми даних, вибір протоколу (REST/GraphQL/tRPC/WebSocket).
2. Проектування контракту — OpenAPI або SDL (GraphQL) до першого рядка коду.
3. Розробка — реалізація за контрактом, модульні тести на кожен ендпоінт.
4. Навантажувальне тестування — k6: 500 віртуальних користувачів, 10 хвилин, p95 latency ≤ 200ms.
5. Деплой — CI/CD з перевіркою зворотної сумісності, автоматична публікація документації.
6. Навчання команди — передача Postman-колекції або Playground, інструкція з підключення.

Що входить в роботу (deliverables)

• OpenAPI 3.1 специфікація (або SDL для GraphQL).
• Згенеровані клієнтські типи для TypeScript / Dart / Kotlin.
• Набір автотестів з покриттям всіх ендпоінтів (модульні + інтеграційні).
• Навантажувальні тести (k6) і звіт (p50/p95/p99 latency, RPS).
• Документація в Swagger UI / Redoc / GraphiQL.
• Навчання команди (2–4 години воркшопу).
• Підтримка протягом 30 днів після здачі (за договором).

Наш досвід

• 10+ років на ринку розробки API.
• 200+ завершених проектів (REST, GraphQL, WebSocket, tRPC).
• 50+ сертифікованих інженерів (AWS, Kubernetes, API Design).
• Економія на трафіку в середньому 85% при переході з REST на GraphQL для мобільних додатків.
• 100% зворотна сумісність — жодного зламаного клієнта за останні 3 роки.

Терміни

Розробка API для типового SaaS-проекту з 30–50 ендпоінтами: від 3 до 8 тижнів залежно від складності бізнес-логіки та кількості зовнішніх інтеграцій. Міграція існуючого REST API на GraphQL — від 2 до 6 тижнів. Додавання WebSocket-шару до готового бекенду — від 1 до 3 тижнів. Вартість розраховується індивідуально після аудиту. Отримайте консультацію — зв'яжіться з нами, щоб обговорити ваш проект.