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-бэкенд.