Системные настройки

Настройки лежат в Система → Системные настройки, пространство имён mxapi, и разложены по областям: доступ и контексты, лимиты и пагинация, журнал и отладка.

Доступ и контексты

Ключ	По умолчанию	Что делает
mxapi.enabled	1	Выключатель API. При 0 любой запрос получает 503 и код service_disabled
mxapi.route_prefix	/mxapi/v1	Публичный префикс маршрутов. При изменении нужно поправить и правило веб-сервера — Маршрутизация
mxapi.context	mgr	Контекст MODX по умолчанию: в нём проверяются права и выполняются процессоры, если эндпоинт не объявил свой
mxapi.allow_request_context	0	Разрешить вызывающей системе выбирать контекст заголовком X-MxApi-Context. Только для эндпоинтов, объявивших это в метаданных. Выключено по умолчанию: расширяет поверхность атаки, нужно на мультисайте
mxapi.token_ttl	86400	Время жизни выданного токена, сек. У клиента интеграции может быть своё — Время жизни токена
mxapi.trusted_proxies	пусто	Адреса прокси, для которых учитывается X-Forwarded-For при определении IP клиента. Для всех остальных заголовок игнорируется — иначе IP-фильтр клиента обходится подделкой
mxapi.catalog_filter	all	Что показывать в каталоге и OpenAPI: all, scope или permission — Режимы видимости
mxapi.cors_origins	пусто	Разрешённые Origin через запятую. Пусто — заголовки CORS не отдаются вовсе. Значение * разрешает любой источник

Лимиты и пагинация

Ключ	По умолчанию	Что делает
mxapi.default_limit	100	Размер страницы по умолчанию для списочных эндпоинтов
mxapi.max_limit	1000	Жёсткий потолок для limit: больший запрос молча ужимается до этого значения
mxapi.rate_limit_per_minute	120	Лимит запросов в минуту; 0 — выключено. Считается по клиенту (при выпуске по паролю — по пользователю, до аутентификации — по IP). У клиента может быть свой rate_limit

Счётчик частоты живёт в кэше и не атомарен: при одновременных запросах возможен недосчёт на единицы. Для защиты от перебора и лавины этого достаточно, для точного учёта потребления — нет, и такой задачи механизм не решает.

Журнал и отладка

Ключ	По умолчанию	Что делает
mxapi.log_reads	0	Писать в журнал успешные чтения. Изменяющие вызовы и любые ошибки пишутся всегда
mxapi.log_lifetime	2592000	Срок хранения записей журнала, сек (30 суток). 0 — не чистить
mxapi.debug	0	Отдавать детали внутренних ошибок в ответе. Только для отладки: в обычном режиме клиент получает нейтральный internal_error, а подробности уходят в лог MODX

Уборка протухших токенов и старых записей журнала выполняется автоматически, не чаще раза в час, в рамках обычного запроса. Крон не нужен.

Проектный файл core/config/mxapi.php

Файл сайта важнее системных настроек: он лежит под версионным контролем проекта и описывает именно эту установку, поэтому не разъезжается с кодом при переносе дампа базы между стендом и продом.

Порядок чтения конфигурации: умолчания пакета → системные настройки MODX → файл сайта.

Образец с пояснениями — core/components/mxapi/config.example.php; скопируйте его в core/config/mxapi.php.

<?php

return [
    'route_prefix' => '/mxapi/v1',
    'token_ttl' => 86400,
    'context' => 'mgr',

    // Провайдеры эндпоинтов (MxApi\Core\Provider\ProviderInterface).
    'providers' => [
        // 'MyReviews\\Api\\Provider',
    ],

    // Дополнительные промежуточные обработчики запроса.
    'middleware' => [],

    // Проектные эндпоинты; класс вне автозагрузки пакета — укажите file.
    'endpoints' => [
        // ['class' => 'MyReviews\\Api\\Endpoint\\ReviewsStatsEndpoint',
        //  'file' => MODX_CORE_PATH . 'components/myreviews/src/Endpoint/ReviewsStatsEndpoint.php'],
    ],

    // Алиасы исторических маршрутов: путь => идентификатор эндпоинта.
    'route_aliases' => [
        // '/v1/reviews' => 'reviews.list',
    ],
];

Ключи providers, middleware, endpoints и route_aliases существуют только в файле — системных настроек с такими именами нет намеренно. Имя класса в базе означало бы, что состав API живёт в дампе, а правка настройки в админке начинала бы влиять на то, какие классы инстанцирует ядро.

route_aliases нужны там, где интеграция уже ходит на исторический адрес: старый путь остаётся рабочим, указывая на тот же эндпоинт, что и новый.

Подробнее о провайдерах и своих эндпоинтах — Свои эндпоинты.