REST API для MODX Headless CMS: налаштування під SPA

Налаштування REST API для MODX як Headless CMS

Уявіть: у вас інтернет-магазин на MODX, що працює 5 років, і marketing вимагає мобільний застосунок, а розробникам потрібен JSON API, щоб підключити React-фронтенд. Або сайт-візитка, де контент-менеджери редагують статті в адмінці, а публікуються вони в Telegram-боті та на Headless CMS. MODX — потужна CMS, але без REST API з коробки. Рішення: кастомний конектор, пакет modREST, або повна реалізація через снипети з header('Content-Type: application/json'). Ми допоможемо обрати оптимальний варіант і налаштуємо REST API під ключ. Наш досвід: понад 70 успішних проєктів, 5+ років на ринку, сертифіковані спеціалісти.

Проблеми, які вирішуємо

• Відсутність стандартного 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 ендпоінтів: каталог, товар, фільтри, пошук, корзина). Наш підхід у 3 рази швидший за використання звичайних снипетів при масових запитах.

Порівняння варіантів реалізації

Для продакшену рекомендуємо кастомний клас — максимальний контроль і безпека. Процесорна реалізація в 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: https://frontend.example.com'); $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.example.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.example.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); 

Процес роботи і що входить

1. Аналітика — вивчаємо поточну структуру контенту, визначаємо ендпоінти та модель даних. Результат: специфікація API.
2. Проєктування — розробляємо REST API: маршрути, методи, формати відповідей, схеми аутентифікації (JWT або API-ключ).
3. Реалізація — пишемо снипети або процесори, налаштовуємо CORS, додаємо вебхуки для сповіщення фронтенду про зміни.
4. Тестування — перевіряємо навантаження (до 1000 запитів/сек), помилки, безпеку (Postman/Insomnia + автоматичні тести).
5. Деплой — викладаємо на продакшен, налаштовуємо кешування (Redis, TTL=10 сек), моніторинг (New Relic).

Відзначимо: що входить: REST API для читання та запису контенту (CRUD), аутентифікація, документація README з прикладами запитів, налаштування CORS, вебхуки, передача доступів та навчання вашого розробника, гарантія 30 днів. Економія часу: до 70% порівняно з розробкою з нуля, що на типовому проєкті становить близько 100 000 ₽ зниження витрат.

Строки та вартість

Вартість розраховується індивідуально — оцінимо проєкт протягом одного робочого дня. Середній бюджет налаштування варіюється від 45 000 до 150 000 ₽ залежно від складності. Для порівняння, аналогічна розробка з нуля обходиться в 2–3 рази дорожче.

Типові помилки при реалізації

• Не налаштований 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, сертифіковані спеціалісти, повний цикл від аналітики до деплою.