GraphQL Persisted Queries: прискорюємо API в рази

Ми часто стикаємося з ситуацією: клієнтський додаток надсилає величезні GraphQL-запити (наприклад, query { user { posts { comments { author { ... } } } } }), які «важать» 10–15 КБ. На мобільному інтернеті це дає TTFB у 3–5 секунд. Persisted Queries вирішують проблему кардинально: замість повного тіла запиту клієнт надсилає лише SHA256-хеш (44 байти). Сервер (або CDN) повертає кешований відповідь. Це знижує трафік на 60% і дозволяє кешувати запити на рівні HTTP. За оцінками Apollo, APQ зменшують розмір запиту в 20 разів для повторних викликів у порівнянні зі звичайними запитами.

Наш досвід: за останні роки ми впровадили цю техніку в 30+ проектах. В одному з кейсів (інтернет-магазин з мільйоном товарів) APQ скоротили розмір запитів з 8 КБ до 400 байт, а LCP впало з 3.2 с до 1.1 с. Гарантуємо чисту реалізацію без просадки з безпеки. Впроваджуємо Persisted Queries під ключ за 2-5 днів.

Як працюють Automatic Persisted Queries (APQ)?

APQ — двофазний протокол. Клієнт спочатку надсилає POST-запит лише з хешем. Якщо кеш сервера не містить запит — повертається 404. Тоді клієнт повторює запит з повним тілом. Сервер зберігає пару хеш→запит і повертає дані. Всі наступні виклики — лише хеш, причому можна перейти на GET-запити, які кешуються на CDN. Це прискорює відповідь у 3-5 разів порівняно з без кешування.

Клієнт          Сервер          CDN/Cache
  │                │                │
  │ POST {hash}    │                │
  │───────────────>│                │
  │ 404 Not Found  │                │
  │<───────────────│                │
  │                │                │
  │ POST {hash + query body}        │
  │───────────────>│                │
  │ {data}  [зберегти hash→query]   │
  │<───────────────│                │
  │                │                │
  │ GET ?hash=...  │                │
  │──────────────────────────────>  │
  │               {data} з кеша     │
  │<──────────────────────────────  │

Порівняння підходів: APQ vs Registered PQ vs відсутність PQ

Оптимізація GraphQL запитів за допомогою Persisted Queries підвищує продуктивність API та покращує Core Web Vitals (LCP, FID). GraphQL кешування на CDN зменшує навантаження на сервер.

Замовте впровадження Persisted Queries — ми покажемо метрики до та після на тестовому стенді. Оцінимо ваш проект безкоштовно.

Чому варто використовувати Registered Persisted Queries?

Registered Persisted Queries (RPQ) — це APQ + білий список. У продакшен дозволені лише запити, чиї хеші є в маніфесті. Це виключає атаки через інтроспекцію схеми або довільні мутації, забезпечуючи високий рівень GraphQL безпеки. Маніфест генерується з клієнтського коду на етапі збірки.

# Генерація маніфесту з клієнтських операцій
npx generate-persisted-query-manifest \
  --documents "src/**/*.graphql" \
  --output persisted-query-manifest.json

// persisted-query-manifest.json (фрагмент)
{
  "format": "apollo-persisted-query-manifest",
  "version": 1,
  "operations": [
    {
      "id": "dc67510fb4289672bea757e862d6b00e...",
      "name": "GetPosts",
      "type": "query",
      "body": "query GetPosts($limit: Int) { posts(first: $limit) { ... } }"
    }
  ]
}

На сервері достатньо middleware, яке підставляє тіло запиту з маніфесту та відхиляє невідомі хеші.

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

Як ми впроваджуємо Persisted Queries: покроково

1. Аудит поточного GraphQL API: аналіз розміру запитів, частоти дублювання, використовуваного кешування.
2. Проектування: вибір підходу (APQ або RPQ), визначення TTL, налаштування Redis для розподіленого кеша.
3. Реалізація на клієнті: впровадження createPersistedQueryLink в Apollo Client або аналогічного для Relay/Urql.
4. Реалізація на сервері: підключення APQ (в Apollo Server вбудоване), налаштування кеша, додавання middleware для RPQ при необхідності.
5. Тестування: перевірка коректності кешування, моніторинг хіт-ратів.
6. Деплой та CDN: налаштування Nginx для кешування GET-запитів, включення Cloudflare або Vercel Edge.

Що входить в роботу

• Документування схеми та маніфесту.
• Налаштування моніторингу влучень у кеш (Prometheus/Grafana).
• Навчання команди підтримці та оновленню маніфесту.
• Пост-релізна підтримка протягом 2 тижнів.
• Передача доступу до репозиторію та документації.

Ми застосовуємо перевірені конфіги. Приклад налаштування Nginx:

proxy_cache_path /var/cache/nginx/graphql
  levels=1:2 keys_zone=graphql:10m max_size=100m
  inactive=1h use_temp_path=off;

location /graphql {
  if ($request_method = GET) {
    proxy_cache graphql;
    proxy_cache_key "$uri$is_args$args";
    proxy_cache_valid 200 5m;
    proxy_cache_use_stale error timeout updating;
    add_header X-Cache-Status $upstream_cache_status;
  }
  proxy_pass http://api_backend;
}

Строки та вартість

Базова настройка APQ з Redis та CDN — від 1 до 2 робочих днів. Повний цикл з Registered Persisted Queries, маніфестом та моніторингом — від 3 до 5 днів. Вартість розраховується індивідуально в залежності від складності схеми та кількості клієнтів. Економія на інфраструктурі може сягати 30%.

Прискорте свій GraphQL API — пишіть нам для оцінки вашого проекту. Покажемо метрики до та після на тестовому стенді. Оцінимо проект безкоштовно.

Розробка 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 тижнів. Вартість розраховується індивідуально після аудиту. Отримайте консультацію — зв'яжіться з нами, щоб обговорити ваш проект.