Настройка Kirby как Headless CMS через API: KQL, REST, аутентификация

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