REST API¶

Forum Pro добавляет свои маршруты в плагин API Grav под /api/v1/forum-pro/. Область «Форум» в Admin Next построена на этих маршрутах, и участники могут через них читать, создавать темы, отвечать, редактировать, ставить реакции и жаловаться — то есть скрипт или бот может делать то же, что участник на форуме. Пути ниже опускают префикс /api/v1.

Аутентификация¶

Используйте любые учётные данные, которые принимает плагин API:

• Ключ API, отправляемый как X-API-Key. Создайте его в Admin Next (ваша учётная запись, затем API Keys) или на сервере через bin/plugin api keys:generate --user=<username>.
• JWT из POST /auth/token, отправляемый как X-API-Token (так делает Admin Next).

curl -k "https://example.test/api/v1/forum-pro/structure" -H "X-API-Key: $KEY"

Кто что может вызывать¶

Есть два вида маршрутов, и авторизуются они по-разному.

Маршруты контента (чтение и запись тем и сообщений) действуют от имени участника форума, связанного с вызывающей учётной записью. Они не требуют никаких прав Grav, даже api.access. Форум решает сам, в точности по тем правилам, которые применяет на сайте: права категории для чтения, создания тем и ответов, закрытые темы и категории, окно редактирования, блокировки, ограничения частоты, оценка спама, премодерация и ограничения предварительной учётной записи. Сообщение, созданное через API, — такое же, как созданное на форуме: оно отправляет уведомления, учитывается в счётчиках и появляется в реальном времени точно так же.

Участник — это связанная с учётной записью учётная запись форума, создаваемая при первом обращении так же, как при первом посещении (учётные записи Grav). Запись в контент отклоняется, когда:

• auth.grav_members равен false, то есть учётные записи Grav не являются участниками форума (403 You must be logged in to …).
• Учётная запись форума приостановлена или удалена.
• Учётная запись ещё не выбрала имя пользователя на форуме.
• Категория не разрешает это группам участника.
• Форум в режиме только для чтения (503). Сотрудники продолжают писать, если не включён maintenance.include_staff, — как и на форуме.

Учётная запись, у которой есть admin.forum-pro.moderate, admin.forum-pro.admin или api.super, либо роль модератора, считается на этих маршрутах сотрудником и в пределах своей области модерации может редактировать и удалять чужие сообщения и менять темы.

Маршруты управления (структура, очередь, блокировки, модераторы, группы, теги, участники, приглашения, статус и метрики) требуют api.access плюс право Forum Pro (Права). В таблицах admin — это admin.forum-pro.admin, а moderate — admin.forum-pro.moderate; admin и api.super считаются обоими. Режим только для чтения не закрывает их, как не закрывает и область «Форум» в Admin Next.

Ключи с областями действия¶

Ключ, созданный без областей действия, а также JWT и сессия имеют полный доступ учётной записи: ключ участника пишет от имени этого участника, а ключ модератора — модерирует. Ключ, созданный с областями действия, ограничен ими:

Область действия никогда не добавляет полномочий, которых у учётной записи нет. Ключу модератора, которому нужно менять темы, нужны и api.forum-pro.post, и admin.forum-pro.moderate; с одним только api.forum-pro.post он пишет как обычный участник. Области задаются при создании ключа — через POST /users/{username}/api-keys и {"name": "Forum bot", "scopes": ["api.forum-pro.post"]}.

Для бота или интеграции создайте отдельную учётную запись Grav, один раз войдите на форум под ней, чтобы выбрать имя пользователя, и создайте ключ на этой учётной записи с областью api.forum-pro.post. Тогда её сообщения будут носить собственное имя, и больше она ничего не сможет.

Публичное чтение¶

Четыре маршрута чтения — GET /forum-pro/structure, GET /forum-pro/categories/{id}/topics, GET /forum-pro/topics/{id} и GET /forum-pro/topics/{id}/posts — отвечают без учётных данных. Гость получает то, что гость может читать на форуме; если отправить ключ, ответ включает и то, что может читать этот участник. Тема, которой вызывающий не видит, отвечает 404 — так же, как несуществующая. При включённом gate.private у форума нет публичного API, и этим маршрутам тоже нужны учётные данные.

Соглашения¶

• Ответы оборачивают полезную нагрузку в data. Списки принимают page и per_page и несут meta.pagination (page, per_page, total, total_pages) и links.
• Ошибки — problem details (application/problem+json) с status, title и detail. Причина отказа форума находится в detail: 422 Title must be between 3 and 255 characters, 403 You are not allowed to reply in this category, 409 This topic is closed.
• Время — секунды epoch в UTC.
• Тела сообщений передаются в Markdown в body_md и рендерятся на сервере, вместе с упоминаниями и цитатами. Чтение возвращает уже отрендеренный body_html.
• Записи отправляют заголовок X-Invalidates (forum:topic:<id>, forum:category:<id>, forum:structure, …), чтобы Admin Next перезапрашивал изменившееся. GET /forum-pro/topics/{id} отправляет ETag.

Маршруты¶

Чтение¶

Темы и сообщения¶

Тема или ответ может появиться в состоянии pending, а не опубликованным — когда категория проводит премодерацию участника или оценка спама удерживает его на проверку. Тогда он появляется после одобрения модератора.

Модерация¶

Структура¶

Модераторы, группы и теги¶

Участники и приглашения¶

Статус и метрики¶

Быстрая проверка через curl¶

KEY=...   # ключ API учётной записи, от имени которой пишет бот
BASE=https://example.test/api/v1/forum-pro

# Найти идентификатор категории
curl -k "$BASE/structure" -H "X-API-Key: $KEY"

# Создать в ней тему
curl -k -X POST "$BASE/topics" -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"category_id": 3, "title": "Nightly build 2.0.4 is out", "body_md": "Changes since yesterday: ..."}'

# Ответить в тему 9434
curl -k -X POST "$BASE/topics/9434/posts" -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"body_md": "Thanks, that fixed it for me."}'

См. также¶

• Администрирование
• Участники и учётные записи
• Модерация
• Grav API: аутентификация