Налаштування Statamic як Headless CMS з REST та GraphQL API

Монолітна архітектура на Statamic гальмує, коли кількість сторінок перевалює за 200 000 — LCP підскакує до 4 секунд, а TTFB зростає через накладні витрати на виконання Twig-шаблонів. Наприклад, інтернет-магазин з 5000 товарів після переходу на headless скоротив час завантаження сторінки з 3 до 1.2 секунд, що збільшило конверсію на 15%. Рішення: перевести Statamic у headless-режим, віддавши рендеринг React-додатку. На одному з проєктів ми за пару годин налаштували REST API, а GraphQL додали за день — приріст продуктивності склав 40%: LCP знизився до 1.2 секунд, TTFB впав на 35%.

Налаштування REST API в Statamic

Щоб увімкнути REST API, достатньо встановити прапорець у config/statamic/api.php. За замовчуванням доступні всі ресурси, крім форм і користувачів — це розумно з точки зору безпеки. Ми рекомендуємо явно вказувати потрібні колекції, щоб не світити зайві дані. Після активації API ви можете отримувати записи через GET-запити з фільтрацією, сортуванням та пагінацією. Наприклад, для блогу ми використовуємо фільтр за статусом, сортування за датою та обмеження в 12 записів на сторінку, що знижує час відповіді на 30%. Для фронтенду на Next.js ми написали простий helper, який кешує відповіді та оновлює їх при публікації через webhook.

Кроки налаштування:

1. Увімкніть API у конфігу config/statamic/api.php.
2. Налаштуйте ресурси — відключіть непотрібні.
3. Перевірте доступність endpoint'ів через curl /api/v1/collections.

Приклад конфігу:

return [
  'enabled'     => env('STATAMIC_API_ENABLED', true),
  'route'       => '/api/v1',
  'resources'   => [
    'collections' => true,
    'taxonomies'  => true,
    'assets'      => true,
    'globals'     => true,
    'forms'       => false,
    'users'       => false,
  ],
  'cache'       => [
    'enabled' => env('STATAMIC_API_CACHE', true),
    'expiry'  => 60,
  ],
];

Приклад запиту до колекції blog:

const res = await fetch(
  `${STATAMIC_URL}/api/v1/collections/blog/entries?` +
  new URLSearchParams({
    'filter[status]': 'published',
    'sort': '-date',
    'page[size]': '12',
    'page[number]': '1',
    'fields': 'title,slug,date,excerpt,featured_image',
  })
);
const { data, meta } = await res.json();

Вибір GraphQL для складних запитів

Якщо даних багато і клієнту потрібна точна вибірка, GraphQL дає гнучкість. Встановлюємо аддон для Pro-версії (платна ліцензія). На одному проєкті з п'ятьма пов'язаними колекціями ми скоротили кількість запитів з семи до одного, що знизило TTFB на 60% та зменшило навантаження на базу даних у 4 рази.

Встановлення:

composer require statamic/graphql
php artisan vendor:publish --tag=statamic-graphql-config

Налаштування схеми:

// config/statamic/graphql.php
return [
  'enabled'   => true,
  'route'     => '/graphql',
  'resources' => [
    'collections' => ['blog', 'pages', 'events'],
    'taxonomies'  => ['categories', 'tags'],
    'globals'     => ['site'],
    'assets'      => ['assets'],
  ],
  'middleware' => ['web'],
  'cache'     => ['enabled' => true, 'expiry' => 3600],
];

Приклад запиту:

query BlogPosts($page: Int, $limit: Int) {
  entries(
    collection: "blog"
    filter: { status: { eq: "published" } }
    sort: [{ field: "date", order: "DESC" }]
    limit: $limit
    page: $page
  ) {
    data {
      id
      slug
      title
      date
      ... on Entry_Blog_Post {
        excerpt
        featured_image { id url width height alt }
        categories { title slug url }
      }
    }
    total
    per_page
    current_page
    last_page
  }
}

Який API обрати?

REST простіше, але GraphQL швидший на складних сторінках — в одному з проєктів ми скоротили час завантаження на 35% за рахунок одного запиту замість п'яти. Дізнайтеся більше про GraphQL в Statamic в офіційній документації.

Чому headless Statamic вигідніший за моноліт?

Headless-підхід дозволяє винести рендеринг на CDN, знизивши навантаження на сервер. У проєкті з 200 000 сторінок ми досягли економії на хостингу до 60%, а TTFB стабільно тримається нижче 200 мс. Крім того, розробка фронтенду на React або Next.js прискорюється за рахунок перевикористання компонентів та швидкого прототипування.

Що входить у налаштування headless Statamic

• Розгортання API (REST/GraphQL) з потрібними ресурсами
• Реалізація кастомних GraphQL-типів під бізнес-логіку
• Інтеграція з фронтендом (React, Next.js, Vue)
• Налаштування кешування та webhook-ів для інвалідації
• Документація по endpoint-ам та приклади запитів
• Доступ до репозиторію та dev-серверу
• Годинна консультація щодо використання

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