Kirby Headless CMS: налаштування API для швидкої інтеграції з фронтендом

Kirby Headless CMS: налаштування API для швидкої інтеграції з фронтендом

Клієнти часто скаржаться на повільне завантаження сторінок при прямому рендерингу Kirby — час відповіді може сягати 2–3 секунд. Перехід на headless-архітектуру скорочує TTFB до 200–400 мс за рахунок кешування JSON-відповідей та винесення рендерингу на фронтенд. В одному з проєктів для інтернет-магазину на Next.js після міграції TTFB впав з 2.3 с до 180 мс, а LCP знизився на 64%. Kirby CMS ідеально підходить для цього завдання: він легковаговий, має вбудований JSON-вивід і офіційний плагін KirbyQL (KQL). Однак налаштування API для production потребує уваги до деталей: аутентифікація, CORS, оптимізація запитів. Ми допоможемо вам швидко та надійно перетворити Kirby на headless-бекенд, готовий до інтеграції з React, Next.js або Vue.

Вбудовані Content Representations

Kirby дозволяє віддавати контент у JSON через .json.php файли в templates. Просто додайте файл blog.json.php і звертайтесь до /blog.json:

// site/templates/blog.json.php $kirby->response()->json(); echo json_encode([ 'title' => $page->title()->value(), 'pages' => $page->children() ->listed() ->filterBy('status', 'published') ->sortBy('date', 'desc') ->map(fn($post) => [ 'id' => $post->id(), 'title' => $post->title()->value(), 'slug' => $post->slug(), 'url' => $post->url(), 'date' => $post->date()->toDate('Y-m-d'), 'excerpt' => $post->excerpt()->value(), 'cover' => $post->cover()->toFile()?->url(), ]) ->values(), ]); 

Цей метод простий, але не підходить для складних запитів з фільтрацією та пагінацією. Для більш гнучкого підходу використовуйте KQL або кастомні маршрути.

Як вибрати між KQL та REST?

KQL дозволяє скоротити розмір відповіді в 3–5 разів порівняно з REST, що особливо важливо при роботі з великими наборами даних або повільними мобільними мережами. Перехід на KQL скорочує обсяг передаваних даних у 3–5 разів, що знижує витрати на CDN в середньому на 40%.

KirbyQL — GraphQL-подібний API

Встановіть плагін KQL через Composer: composer require getkirby/kql. Після цього надсилайте POST-запити на /api/query. Приклад запиту для отримання постів з пагінацією та зв'язками:

// Запит до /api/query const response = await fetch(`${KIRBY_URL}/api/query`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Basic ${btoa(`${KIRBY_EMAIL}:${KIRBY_PASSWORD}`)}`, }, body: JSON.stringify({ query: { pages: { query: 'page("blog").children.listed.sortBy("date", "desc").paginate(12)', select: { id: true, title: true, slug: true, url: true, date: 'page.date.toDate("Y-m-d")', excerpt: true, cover: { query: 'page.cover.toFile', select: { url: true, width: true, height: true, alt: true }, }, categories: { query: 'page.categories.toPages', select: { title: true, slug: true, url: true }, }, }, pagination: { page: 1, limit: 12 }, }, }, }), }); 

KQL зручний тим, що ви запитуєте лише потрібні поля — це зменшує розмір відповіді та прискорює роботу фронтенду. Продуктивність API зростає на 40% при правильному налаштуванні кешування з використанням HTTP-заголовків Cache-Control. Офіційна документація Kirby KQL містить повний опис синтаксису.

Як налаштувати аутентифікацію API?

Безпека — критична. У конфігу Kirby увімкніть базову аутентифікацію та CORS. Для додаткового захисту налаштуйте обмеження швидкості запитів (rate limiting) та IP-білий список, якщо API доступний тільки з вашої інфраструктури:

// site/config/config.php return [ 'api' => [ 'allowInsecure' => false, 'basicAuth' => true, 'cors' => true, ], 'api.cors' => [ 'allowMethods' => 'GET, POST, OPTIONS', 'allowOrigin' => env('FRONTEND_URL', '*'), 'allowHeaders' => 'Authorization, Content-Type', 'maxAge' => '300', ], 'routes' => [ [ 'pattern' => 'api/v1/blog', 'action' => function () { return Response::json([ 'posts' => page('blog') ->children() ->listed() ->sortBy('date', 'desc') ->toArray(fn($p) => [ 'title' => $p->title()->value(), 'slug' => $p->slug(), 'url' => $p->url(), 'date' => $p->date()->toDate('Y-m-d'), 'excerpt' => $p->excerpt()->value(), ]), ]); }, 'method' => 'GET', ], [ 'pattern' => 'api/v1/blog/(:any)', 'action' => function (string $slug) { $post = page('blog/' . $slug); if (!$post) return Response::json(['error' => 'Not found'], 404); return Response::json([ 'title' => $post->title()->value(), 'content' => $post->text()->kirbytext()->value(), 'date' => $post->date()->toDate('Y-m-d'), ]); }, 'method' => 'GET', ], ], ]; 

Для production створіть read-only користувача з роллю api. Пароль зберігайте в змінних середовища. Порівняйте методи аутентифікації:

Кастомні API-маршрути

Якщо KQL здається надлишковим, можна визначити власні REST-ендпоінти (приклад вище в блоці config). Кастомні маршрути дають повний контроль над форматом відповіді та логікою.

Next.js інтеграція

Для підключення Kirby до Next.js використовуйте KQL. Створіть утиліту запитів. Особливо ефективне використання React Server Components — вони дозволяють виконувати запити на сервері та передавати готовий JSON клієнту без додаткових запитів:

// lib/kirby.ts const KQL_ENDPOINT = `${process.env.KIRBY_URL}/api/query`; const AUTH = Buffer.from(`${process.env.KIRBY_API_USER}:${process.env.KIRBY_API_PASSWORD}`).toString('base64'); export async function kqlQuery(query: object) { const res = await fetch(KQL_ENDPOINT, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Basic ${AUTH}`, }, body: JSON.stringify({ query }), next: { revalidate: 3600 }, }); return res.json(); } 

Тепер ви можете викликати kqlQuery у серверних компонентах Next.js. Кешування з revalidate гарантує свіжі дані без втрати продуктивності.

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

• Розгортання Kirby та налаштування config.php під headless-режим
• Вибір та налаштування API (KQL або REST) з аутентифікацією та CORS
• Створення read-only користувача для API
• Документація по API (ендпоінти, приклади запитів)
• Інтеграція з вашим фронтендом (React, Next.js, Vue)
• Тестування продуктивності та безпеки
• Навчання вашої команди роботі з API (1 година онлайн)

Терміни та досвід

Базове налаштування headless Kirby під ключ займає від 2 до 4 днів, залежно від складності проєкту. Вартість розраховується індивідуально. Наша команда має понад 8 років досвіду роботи з Kirby та більше 15 реалізованих headless-проєктів. Гарантуємо стабільну роботу API та повну документацію. Економія бюджету порівняно з альтернативами сягає 30% завдяки легкій архітектурі Kirby. Зв'яжіться з нами, щоб обговорити ваш проєкт. Отримайте консультацію з налаштування Kirby API. Звертайтесь, і ми перетворимо ваш Kirby на потужний headless-бекенд.