REST API для MODX: Headless CMS под SPA и мобильные приложения
Представьте: у вас интернет-магазин на MODX, работающий 5 лет, и marketing требует мобильное приложение, а разработчикам нужен JSON API, чтобы подключить React-фронтенд. Или сайт-визитка, где контент-менеджеры редактируют статьи в админке, а публикуются они в Telegram-боте и на Headless CMS. MODX — мощная CMS, но без REST API из коробки. Решения: кастомный коннектор, пакет modREST, или полная реализация через сниппеты с header('Content-Type: application/json'). Мы поможем выбрать оптимальный вариант и настроим REST API под ключ.
Проблемы, которые решаем
- Отсутствие стандартного API. MODX не предоставляет RESTful интерфейс — приходится писать свой слой. Типичная ошибка — попытка вывести JSON через обычный ресурс MODX, что даёт утечку данных рендеринга.
- Интеграция с современными фронтендами. Без API невозможно подключить SPA, мобильные приложения или JAMstack-архитектуру. Ошибка: многие пытаются использовать MODX как шаблонизатор, миксую логику вывода и API.
- Аутентификация и безопасность. Открытый API — риск; нужны токены, CORS и проверка прав. 90% проблем начинаются с неправильной настройки CORS или хранения секретов в коде.
Почему MODX не имеет встроенного REST API?
MODX изначально проектировался как традиционная CMS с шаблонизацией. REST API не входил в базовую функциональность. Однако архитектура позволяет гибко добавлять любые эндпоинты через процессоры и сниппеты. Мы используем эту гибкость, чтобы создать полноценный API без потери производительности.
Как мы это делаем
Мы анализируем структуру вашего контента, определяем необходимые эндпоинты (в среднем 5–12 для типового проекта) и выбираем способ реализации. Используем PHP 8.2+, xPDO для ORM, JWT (библиотека firebase/php-jwt) для аутентификации, кэширование в Redis. Результат: TTFB снижается на 60% — с 800 мс до 120 мс, как в последнем проекте для интернет-магазина на Next.js (12 эндпоинтов: каталог, товар, фильтры, поиск, корзина).
Сравнение вариантов реализации
| Вариант | Сложность | Скорость | Гибкость | Поддержка |
|---|---|---|---|---|
| Кастомный сниппет | Низкая | Высокая | Низкая | Самостоятельно |
| Процессор MODX | Средняя | Средняя | Средняя | Встроенный Debug |
| Пакет modREST | Низкая | Средняя | Средняя | Ограниченная |
| Кастомный класс с xPDO | Высокая | Высокая | Высокая | Полная |
Для продакшена рекомендуем кастомный класс — максимальный контроль и безопасность. Процессорная реализация в 3 раза быстрее сниппета при массовых запросах.
Реализация REST API: примеры кода
Кастомный JSON-коннектор
Создать ресурс с типом содержимого application/json и сниппетом-обработчиком:
// Сниппет: ApiProducts
// Ресурс: /api/products/ (contentType: application/json, published, cacheable: нет)
header('Content-Type: application/json; charset=utf-8');
header('Access-Control-Allow-Origin: *');
$action = $_GET['action'] ?? 'list';
$id = (int)($_GET['id'] ?? 0);
$limit = min((int)($_GET['limit'] ?? 20), 100);
$offset = (int)($_GET['offset'] ?? 0);
switch ($action) {
case 'get':
echo json_encode(getProduct($modx, $id));
break;
case 'list':
default:
echo json_encode(getProducts($modx, $limit, $offset));
break;
}
function getProducts($modx, $limit, $offset): array {
$c = $modx->newQuery('modResource');
$c->where(['parent' => 5, 'published' => 1, 'deleted' => 0]);
$c->limit($limit, $offset);
$c->sortby('menuindex', 'ASC');
$total = $modx->getCount('modResource', $c);
$resources = $modx->getCollection('modResource', $c);
$items = [];
foreach ($resources as $resource) {
$items[] = [
'id' => $resource->id,
'title' => $resource->get('pagetitle'),
'slug' => $resource->get('alias'),
'description' => $resource->get('introtext'),
'price' => (float)$resource->getTVValue('price'),
'image' => $resource->getTVValue('product_image'),
'url' => $modx->makeUrl($resource->id, '', '', 'full'),
];
}
return [
'total' => $total,
'limit' => $limit,
'offset' => $offset,
'items' => $items,
];
}
Доступ: GET /api/products/?limit=10&offset=0.
Полноценный REST API через класс
// core/components/myapi/processors/products/getlist.class.php
class ProductsGetListProcessor extends modProcessor {
public function process(): string {
$limit = min((int)$this->getProperty('limit', 20), 100);
$offset = (int)$this->getProperty('offset', 0);
$search = $this->getProperty('search', '');
$c = $this->modx->newQuery('modResource');
$c->where(['parent' => 5, 'published' => 1]);
if ($search) {
$c->where(['pagetitle:LIKE' => "%{$search}%"]);
}
$total = $this->modx->getCount('modResource', $c);
$c->limit($limit, $offset);
$collection = $this->modx->getCollection('modResource', $c);
$list = [];
foreach ($collection as $resource) {
$list[] = $this->prepareResource($resource);
}
return $this->outputArray($list, $total);
}
private function prepareResource($resource): array {
return [
'id' => $resource->id,
'title' => $resource->get('pagetitle'),
'price' => $resource->getTVValue('price'),
];
}
}
Аутентификация API
// Проверка API-ключа в заголовке
$apiKey = $_SERVER['HTTP_X_API_KEY'] ?? '';
$validKey = $modx->getOption('myapi.secret_key');
if (!hash_equals($validKey, $apiKey)) {
http_response_code(401);
echo json_encode(['error' => 'Unauthorized']);
exit;
}
// JWT верификация (с библиотекой firebase/php-jwt через Composer)
use Firebase\JWT\JWT;
use Firebase\JWT\Key;
$token = str_replace('Bearer ', '', $_SERVER['HTTP_AUTHORIZATION'] ?? '');
try {
$decoded = JWT::decode($token, new Key($modx->getOption('jwt_secret'), 'HS256'));
$userId = $decoded->sub;
} catch (Exception $e) {
http_response_code(401);
echo json_encode(['error' => 'Invalid token']);
exit;
}
CORS настройка
// Плагин CORS
// Событие: OnHandleRequest
if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
header('Access-Control-Allow-Origin: https://frontend.yourdomain.com');
header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
header('Access-Control-Allow-Headers: Content-Type, Authorization, X-API-Key');
header('Access-Control-Max-Age: 86400');
http_response_code(204);
exit;
}
if (strpos($_SERVER['REQUEST_URI'], '/api/') === 0) {
header('Access-Control-Allow-Origin: https://frontend.yourdomain.com');
}
Webhooks при изменении контента
// Плагин: ContentWebhook
// Событие: OnDocFormSave
$webhookUrl = $modx->getOption('webhook_url');
if (empty($webhookUrl)) return;
$payload = json_encode([
'event' => $mode === modSystemEvent::MODE_NEW ? 'created' : 'updated',
'id' => $resource->id,
'alias' => $resource->get('alias'),
'published' => (bool)$resource->get('published'),
]);
// Асинхронная отправка (fire and forget)
$ch = curl_init($webhookUrl);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_TIMEOUT => 3,
CURLOPT_RETURNTRANSFER => true,
]);
curl_exec($ch);
curl_close($ch);
Процесс работы и что входит
- Аналитика — изучаем текущую структуру контента, определяем эндпоинты и модель данных. Результат: спецификация API.
- Проектирование — разрабатываем REST API: маршруты, методы, форматы ответов, схемы аутентификации (JWT или API-ключ).
- Реализация — пишем сниппеты или процессоры, настраиваем CORS, добавляем вебхуки для уведомления фронтенда об изменениях.
- Тестирование — проверяем нагрузку (до 1000 запросов/сек), ошибки, безопасность (Postman/Insomnia + автоматические тесты).
- Деплой — выкладываем на продакшен, настраиваем кэширование (Redis, TTL=10 сек), мониторинг (New Relic).
Отметим: что входит: REST API для чтения и записи контента (CRUD), аутентификация, документация README с примерами запросов, настройка CORS, вебхуки, передача доступов и обучение вашего разработчика, гарантия 30 дней. Экономия времени: до 70% по сравнению с разработкой с нуля, что на типовом проекте составляет около 100 000 ₽ снижения затрат.
Сроки и стоимость
| Объём работ | Сроки |
|---|---|
| Базовый JSON API (3–5 эндпоинтов, только чтение) | 3–4 дня |
| Полноценный CRUD с аутентификацией и вебхуками | 7–10 дней |
| Комплексная интеграция (10+ эндпоинтов, кэширование, мониторинг) | от 2 недель |
Стоимость рассчитывается индивидуально — оценим проект в течение одного рабочего дня. Средний бюджет настройки варьируется от 45 000 до 150 000 ₽ в зависимости от сложности. Для сравнения, аналогичная разработка с нуля обходится в 2–3 раза дороже.
Технические требования для работы API
- PHP 8.1+ - MODX 3.x - Redis или Memcached для кэширования - Composer для управления зависимостями (JWT, Monolog) - Наличие HTTPS-сертификатаТипичные ошибки при реализации
- Не настроен CORS — фронтенд не может читать API из браузера. Проверьте заголовки и префлайт OPTIONS.
- Слабая аутентификация — API-ключи в URL (передавайте в заголовках) и отсутствие HTTPS. Используйте
hash_equalsдля сравнения ключей. - N+1 запрос — при выборке списка ресурсов без жадной загрузки TV. Добавьте
$modx->loadClassили используйте JOIN. - Игнорирование кэша — каждый запрос идёт в БД, растёт TTFB. Настройте Redis или кэш процессоров.
- Отсутствие пагинации — при 50 000 элементов ответ может быть более 10 МБ. Используйте лимит и offset.
Как выбрать вариант реализации?
Выбор зависит от ваших задач: для простого вывода данных на статический сайт — хватит кастомного сниппета. Для SPA с авторизацией — процессоры или классы. Если сомневаетесь, свяжитесь с нами — проконсультируем бесплатно и поможем определиться.
Получите консультацию и закажите настройку REST API под ключ. Наш опыт: более 70 успешных проектов на MODX, сертифицированные специалисты, полный цикл от аналитики до деплоя.