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 | REST |
|---|---|---|
| Гнучкість запитів | Висока (вибір полів, зв'язки) | Низька (фіксований вивід) |
| Складність налаштування | Середня (потрібен плагін) | Низька (вбудовані роути) |
| Продуктивність | Оптимальна (тільки потрібні дані) | Надлишкова (може віддавати зайве) |
| Типовий use-case | Складні frontend-застосунки | Прості блоги або мікросервіси |
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. Пароль зберігайте в змінних середовища. Порівняйте методи аутентифікації:
| Метод | Складність | Безпека | Рекомендація |
|---|---|---|---|
| Basic Auth | Низька | Середня (через HTTPS) | Для малих проєктів |
| JWT | Середня | Висока | Для production |
| 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-бекенд.