Конфигурация¶

Эндпоинты для чтения, обновления и отката областей конфигурации Grav, включая system, site, media, security, plugins, themes и пользовательские области, задаваемые сайтом, а также конфигурацию учётных записей Flex. Для чтения нужно api.config.read, для записи — api.config.write; запись в system, security и plugins/api, а также любой доступ к управляемым инструментами областям scheduler и backups дополнительно требуют суперпользователя API. Конфигурация учётных записей доступна только суперпользователю.

Список разделов конфигурации¶

GET /config

Выводит области конфигурации, которые админка показывает как вкладки. Требуется api.config.read.

Ответ

{"data": ["system", "site", "media", "security", "info"]}

Коды ответов

Список всегда начинается с system и site и заканчивается на info — это клиентская вкладка с информацией о системе, а не читаемая область. Между ними, в алфавитном порядке, идут основные области media и security, а также любые пользовательские области, заданные сайтом, плагином или темой (файл user/config/<name>.yaml с соответствующей схемой конфигурации). backups включается только для суперпользователей, а scheduler в списке никогда не появляется. Настройки плагинов и тем здесь не перечисляются; читайте их как области plugins/{name} и themes/{name}.

Получение конфигурации¶

GET /config/{scope}

Возвращает действующую конфигурацию для области, маскируя секретные значения. Требуется api.config.read.

Параметры

Ответ

{"data": {"title": "My Site", "author": {"name": "Admin", "email": "admin@example.com"}}, "meta": {"overrides": ["title"], "fallback": {"title": "Grav"}}}

Коды ответов

Тело ответа — полная конфигурация выбранного слоя, пересчитанная из YAML-файлов, поэтому чтение с X-Config-Environment: default показывает базовую конфигурацию даже при активном наложенном окружении. Пароли, ключи API и токены возвращаются замаскированными. meta.overrides перечисляет точечные пути конечных значений, которые переопределяет выбранный слой, а meta.fallback показывает значение, к которому каждый из них откатится (см. Откат конфигурации).

ETag вычисляется по сохранённым переопределениям, а не по полному телу ответа, поэтому остаётся действительным после сохранения и повторной загрузки.

Обновление конфигурации¶

PATCH /config/{scope}

Обновляет значения конфигурации с глубоким слиянием. Требуется api.config.write.

Параметры

Запрос

{"title": "Updated Site Title"}

Ответ

{"data": {"title": "Updated Site Title", "author": {"name": "Admin", "email": "admin@example.com"}}, "meta": {"overrides": ["title"], "fallback": {"title": "Grav"}}}

Коды ответов

Тело запроса глубоко сливается с существующей конфигурацией с использованием схемы области, поэтому такие поля, как списки файлов, заменяются, а не сливаются. Валидируются по схеме только поля, значения которых изменились. На диск записываются только значения, отличающиеся от родительского слоя, а значения, заданные через переменные окружения GRAV_CONFIG__*, никогда не сохраняются. Замаскированный секрет, отправленный обратно без изменений, сохраняет своё хранимое значение.

Ответ имеет ту же структуру, что и Получение конфигурации, и содержит заголовок X-Invalidates (config:update:<scope>, а для областей плагинов ещё plugins:update:<name> и plugins:list). Успешное сохранение вызывает onAdminSave, onAdminAfterSave и onApiConfigUpdated.

Поддерживает оптимистичный контроль конкурентного доступа через заголовок If-Match.

Откат конфигурации¶

POST /config/{scope}/revert

Удаляет переопределения из слоя конфигурации, чтобы значения вернулись к нижележащему слою. Требуется api.config.write.

Параметры

Запрос

{"keys": ["pages.theme", "debugger.enabled"]}

Ответ

{"data": {"pages": {"theme": "quark"}, "debugger": {"enabled": false}}, "meta": {"overrides": ["pages.markdown.extra"], "fallback": {"pages.markdown.extra": false}, "reverted": true}}

Коды ответов

Откат ключа в базовом слое позволяет вступить в силу значению по умолчанию из ядра или плагина; откат ключа в слое окружения позволяет вступить в силу базовому значению. Если после отката в файле слоя ничего не остаётся, файл удаляется.

Ответ — действующая конфигурация после отката, с замаскированными секретами, в той же структуре, что и Получение конфигурации. meta.overrides перечисляет пути, которые по-прежнему переопределяют родительский слой, а meta.reverted сообщает, изменилось ли что-либо на диске. Откат того, что слой не переопределяет (например, reset: true, когда у слоя нет файла), всё равно возвращает 200, но meta.reverted равен false и onApiConfigUpdated не вызывается, поэтому вебхук config.updated не отправляется.

Поддерживает оптимистичный контроль конкурентного доступа через заголовок If-Match, используя тот же ETag, что и при получении конфигурации.

Получение конфигурации учётных записей¶

GET /config/accounts

Возвращает конфигурацию учётных записей Flex (flex.accounts, хранится в user/config/flex/accounts.yaml) — вкладку «Конфигурация» в разделе «Пользователи». Требуется admin.super.

Ответ

{"data": {"object": {"compat": {"events": true}}}}

Коды ответов

Этот маршрут имеет приоритет над GET /config/{scope}, поэтому accounts никогда не читается как обычная область.

Обновление конфигурации учётных записей¶

PATCH /config/accounts

Глубоко сливает тело запроса с конфигурацией учётных записей Flex и записывает её в user/config/flex/accounts.yaml. Требуется admin.super.

Запрос

{"object": {"compat": {"events": false}}}

Ответ

{"data": {"object": {"compat": {"events": false}}}}

Коды ответов

Вложенные отображения сливаются, а списки заменяются целиком. Файл всегда записывается в базовый user/config, никогда в слой окружения, а значения, заданные через переменные окружения GRAV_CONFIG__*, на диск не записываются. Ответ содержит заголовок X-Invalidates: config:update:flex/accounts, а сохранение вызывает onApiConfigUpdated с областью flex/accounts.

Поддерживает оптимистичный контроль конкурентного доступа через заголовок If-Match.