mxApi

Единая точка входа публичного API для MODX Revolution. Пакет даёт транспорт, аутентификацию по bearer-токенам, реестр эндпоинтов, каталог и выгрузку OpenAPI. Сами эндпоинты он не поставляет — их приносят провайдеры: другие пакеты или код конкретного сайта.

Из коробки работают только служебные маршруты: выпуск и отзыв токена, каталог эндпоинтов, OpenAPI.

Зачем

Публичный API у MODX-сайта обычно вырастает из одного сниппета «отдать заказы партнёру», а дальше обрастает вторым, третьим и собственной проверкой токена в каждом. mxApi забирает на себя всё, что в этих задачах одинаково: маршрутизацию, аутентификацию, права, лимиты, журнал, — и оставляет разработчику только сам эндпоинт.

Ключевые решения, о которых стоит знать заранее:

Права не изобретаются заново. Запрос выполняется от имени реального пользователя MODX, а право эндпоинта проверяется штатным механизмом политик на namespace mxapi. Дать интеграции больше, чем есть у её пользователя, нельзя.
Токен непрозрачный и живёт в базе (не JWT) — значит отзывается мгновенно. В таблице лежит только sha256-хэш: утечка базы не даёт доступа.
Каталог собирается из живого реестра. Отдельного YAML-файла со спецификацией, который расходится с кодом, не существует: /meta/openapi — это то, что сайт действительно умеет прямо сейчас.

Что внутри

Маршруты под своим префиксом (по умолчанию /mxapi/v1), не пересекающиеся с маршрутами сайта и других пакетов.
Два способа получить токен: по логину и паролю пользователя MODX и по паре client_id/client_secret машинного клиента. См. Токены и аутентификация.
Клиенты интеграций заводятся в админке — на вкладке «mxApi» страницы пользователя: название, набор scope, своё время жизни токена.
Scope поверх прав MODX: эндпоинт объявляет и то, и другое, соответствие берётся из метаданных. См. Права доступа.
Лимит частоты запросов (окно в минуту, свой лимит у клиента) и идемпотентность изменяющих вызовов по заголовку Idempotency-Key.
Журнал обращений: кто, когда, каким токеном, в каком контексте MODX и с каким результатом.
Каталог в админке и OpenAPI 3.0 из живого реестра эндпоинтов. См. Каталог и OpenAPI.

Требования

Пакет выходит двумя линиями. Ядро у них общее — различаются платформенный слой, модели и интерфейс в админке, — поэтому эта документация описывает обе, а различия отмечены врезками.

	MODX 2	MODX 3
Версии пакета	`1.x`	`2.x`
MODX	2.6+	3.0+
PHP	7.4+	8.1+
Дополнительно	—	пакет VueTools — на нём работает интерфейс в админке

Пакет везёт собственный vendor/ (composer, PSR-4), изолированный от других пакетов. При сборке из исходников — composer install --no-dev в core/components/mxapi/.

Версия для MODX 3

Интерфейс в админке (каталог эндпоинтов и вкладка «mxApi» на странице пользователя) построен на Vue и берёт общий фронтенд-стек из пакета VueTools. Без него API работает полностью, а страницы админки сообщат, какого пакета не хватает.

Публичный контракт и имена таблиц у линий совпадают, поэтому сайт, который переезжает с MODX 2 на MODX 3, сохраняет клиентов интеграций, выданные токены и журнал — переносить или мигрировать данные не нужно.

Установка

Поставьте transport-пакет через Пакеты → Установить пакет в менеджере MODX.

Что создаётся при установке

Что	Подробности
Таблицы	`modx_mxapi_client` (клиенты интеграций, секрет только хэшем), `modx_mxapi_token` (выданные токены, в базе `sha256`-хэш), `modx_mxapi_log` (журнал вызовов и аудит)
Системные настройки	Ключи `mxapi.*` — префикс маршрутов, TTL токена, лимиты, журнал, CORS. См. Настройки
Права и политика	Шаблон политики `mxapiTemplate`, политика `mxapiDefault` и права `mxapi_`. Группам политика не назначается* — доступ выдаётся вручную, см. Права доступа
Меню	Компоненты → mxApi — каталог эндпоинтов и выгрузка OpenAPI
Плагин	`mxApiUserClients` — вкладка «mxApi» на странице правки пользователя
События	`mxApiOnRegisterEndpoints`, `mxApiOnBeforeRequest`, `mxApiOnBeforeEndpointRun`, `mxApiOnAfterEndpointRun`, `mxApiOnResponse`

Таблицы при удалении пакета не дропаются: в них боевые учётки и аудит.

Маршрутизация на веб-сервере

Публичный префикс задаётся настройкой mxapi.route_prefix (по умолчанию /mxapi/v1). Запросы с этим префиксом нужно направить в точку входа пакета — assets/components/mxapi/index.php.

nginx

location ^~ /mxapi/ {
    try_files $uri /assets/components/mxapi/index.php$is_args$args;
}

Блок размещается до общего location / сайта.

Apache

Правила добавляются в .htaccess в корне сайта выше штатных правил MODX (тех, что заканчиваются перенаправлением на index.php): иначе MODX перехватит запрос раньше и ответит страницей 404 сайта.

apache

RewriteEngine On

# Заголовок Authorization до PHP: при mod_php и CGI Apache его не передаёт,
# и bearer-токен теряется. mxApi читает REDIRECT_HTTP_AUTHORIZATION.
RewriteRule ^mxapi/ - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

# Собственно маршрутизация префикса в точку входа пакета.
RewriteRule ^mxapi/(.*)$ assets/components/mxapi/index.php [QSA,L]

Три вещи, которые ломают Apache-вариант чаще всего

Правила ниже правил MODX. Порядок в .htaccess решает всё: правило mxApi обязано стоять до блока RewriteCond %{REQUEST_FILENAME} !-f … RewriteRule ^(.*)$ index.php.
Сайт в подкаталоге. Тогда в этом же файле нужен раскомментированный и поправленный RewriteBase (например RewriteBase /shop/).
Изменённый префикс. При mxapi.route_prefix = /api/mx/v1 в обоих правилах меняется первый сегмент: ^api/mx/.

Вместо строки с E=HTTP_AUTHORIZATION на Apache 2.4.13+ с PHP-FPM или CGI можно включить передачу заголовка директивой (в конфигурации сервера или в том же .htaccess, если это разрешено AllowOverride):

apache

CGIPassAuth On

Достаточно одного из двух способов. Признак того, что заголовок до PHP не доходит: ответ token_required при заведомо верном токене.

Без правки конфигурации веб-сервера

Тот же API доступен напрямую, маршрут передаётся параметром route:

/assets/components/mxapi/index.php?route=/auth/token

Способ рабочий и удобен для проверки установки, но публичным контрактом считается префикс: интегратору сообщается адрес вида https://site.ru/mxapi/v1/....

Проверка установки

bash

curl -i 'https://site.ru/mxapi/v1/meta/endpoints'

Ожидаемый ответ — HTTP 401 и JSON с кодом token_required. Это значит, что маршрут доходит до пакета и API работает; дальше нужен токен — Быстрый старт.

Другие ответы читаются так:

Что пришло	Что это значит
HTML-страница 404 сайта	не сработало правило веб-сервера — MODX перехватил запрос
`not_installed`	нет `vendor/autoload.php` у пакета: установка неполная
`service_disabled` (503)	API выключен настройкой `mxapi.enabled`

Дальше

Быстрый старт — от установки до первого успешного вызова.
Токены и аутентификация — два способа выпуска токена и клиенты интеграций.
Свой эндпоинт: пошагово — как пакету или сайту добавить собственные маршруты, от решения о scope до проверки вызовом.
Справочник эндпоинта — все ключи описания, типы параметров, хуки и события.

handyShop

Утилиты

Настройки

Утилиты

События

Backend API