mxHeadless

REST API gateway для MODX Revolution 3. Отдаёт ресурсы, страницы, элементы, контексты и зарегистрированные xPDO-объекты в JSON. Подходит для Nuxt, Next.js, SvelteKit, мобильных приложений и своих клиентов.

Версия 1.0.42. Лицензия GPL-2.0-or-later. Платных тарифов внутри пакета нет.

Исходники: Ibochkarev/mxHeadless.

Возможности

• Префикс /api/v1 через плагин OnHandleRequest (настраивается)
• В API попадают только зарегистрированные объекты и поля
• Middleware PSR-7/15: CORS, rate limit, CSRF, idempotency, HTTP-кэш, audit, webhooks
• Live OpenAPI и Swagger UI на /api/v1/docs
• API keys (mxh_*), OAuth (mxt_*), сессия менеджера
• Extension API (OnMxHeadlessRegister) для MiniShop3 и своих extras

Требования

	Версия
MODX Revolution	3.2.3+ (в transport указано modx >= 3.0.0, ориентируйтесь на README)
PHP	8.1+
БД	MySQL / MariaDB (InnoDB), xPDO 3

Подробнее: Требования.

Установка

Через modstore.pro в Управление пакетами или сборка transport из исходников:

cd _build
php build.php

Дальше: Установка, Веб-сервер, Быстрый старт.

Базовый URL

https://your-site.example/api/v1

curl -s https://your-site.example/api/v1 | jq
curl -s https://your-site.example/api/v1/health | jq

Интерактивная спецификация: /api/v1/docs. Подробнее: Swagger и OpenAPI.

Без rewrite: assets/components/mxheadless/api.php?route=/v1/health.

Формат ответа

Успех:

{
  "data": {},
  "meta": {
    "total": 100,
    "count": 20,
    "limit": 20,
    "offset": 0,
    "has_more": true
  },
  "links": {
    "self": "/api/v1/resources?limit=20&offset=0",
    "next": "/api/v1/resources?limit=20&offset=20"
  }
}

Ошибки: RFC 9457 (application/problem+json). См. Ошибки.

Как устроен доступ

Объект появляется в API только после регистрации в ObjectRegistry с явными fields, filters и permissions. Имя в URL (resources, products) всегда мапится на ObjectDefinition, не на произвольный PHP-класс. QueryParser пропускает только field, filter и sort из definition.

mxHeadless и mxApi

mxApi даёт транспорт и реестр чужих эндпоинтов. mxHeadless сразу отдаёт ресурсы MODX и зарегистрированные объекты с фиксированным envelope и live OpenAPI. Оба пакета можно держать на разных префиксах.

Быстрые ссылки

Тема	Ссылка
Быстрый старт	quick-start
Системные настройки	settings
Аутентификация	authentication
Resources	api/resources
Swagger и OpenAPI	api/swagger
MiniShop3	extensions/minishop3
Webhooks	operations/webhooks