Перейти к содержанию

Справочник API

Все эндпоинты живут под единственным действием SMF index.php?action=api, а путь к ресурсу передаётся в параметре path:

index.php?action=api;path=v1/members/5

При настроенном правиле перезаписи тот же ресурс адресуется как /api/v1/members/5 — см. Чистые URL. Все пути в таблицах ниже указаны относительно v1, то есть полный адрес — index.php?action=api;path=v1/<path>.

API должен быть включён

Мод поставляется выключенным. Включите его в «Админка → Конфигурация → Настройки модов → RESTful API» («Включить API»). Пока мод выключен, любой эндпоинт отвечает 503 Service Unavailable с кодом ошибки service_unavailable.

Основы запроса

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

Любой запрос требует API-ключ; ключ выбирает пользователя, чьи права применяются. Он берётся из первого доступного источника:

  1. заголовок Authorization: Bearer <key>;
  2. заголовок X-API-Key: <key>;
  3. query-параметр api_key.

Ключи управляются на странице «Админка → Конфигурация → Настройки модов → RESTful API»: каждый ключ — непрозрачный токен, привязанный к id пользователя. Свою схему вместо штатной см. в разделе Свои схемы аутентификации.

Только полностью активированные аккаунты (is_activated = 1) могут работать через API. Отсутствующий, неизвестный или деактивированный ключ даёт 401 с кодом unauthorized.

Префикс версии

Первый сегмент пути — версия контракта API. Принимается только v1; любой другой даёт 404 с кодом not_found и сообщением Unsupported API version: <сегмент>.

Методы

Поддерживаются GET, POST, PUT, PATCH и DELETE. Известный путь с неподдерживаемым методом даёт 405 с кодом method_not_allowed.

Клиенты, которые умеют отправлять только GET и POST, могут переопределить метод заголовком X-HTTP-Method-Override или query-параметром _method:

POST /index.php?action=api&path=v1/members/5&_method=PATCH

Переопределение учитывается только для запросов POST.

Тело запроса

Тело разбирается как JSON, если заголовок Content-Type содержит application/json; иначе используется обычная form-encoded полезная нагрузка. Некорректный JSON даёт 400 с кодом bad_request.

Тело запроса
{
  "username": "demo",
  "email": "demo@example.com"
}

Зарезервированные query-параметры

SMF резервирует board, topic, msg, start и action как query-параметры: если передать один из них, ядро отрисует страницу форума вместо обработки action=api. Поэтому id родителя передаётся в пути (/boards/{board_id}/topics), а не в query-строке. Подробности — в разделе Добавление ресурса.

Пагинация

Коллекции принимают два query-параметра:

  • limit — размер страницы, от 1 до 100, по умолчанию 25;
  • offset — смещение от начала, по умолчанию 0.

Оба значения приводятся к допустимым границам: выход за них не вызывает ошибку, а молча исправляется.

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

Один ресурс

Ответ
{
  "data": {
    "id": 5,
    "username": "demo"
  }
}

Коллекция

Коллекции добавляют метаданные пагинации:

Ответ
{
  "data": [
    { "id": 5, "username": "demo" }
  ],
  "meta": {
    "total": 42,
    "limit": 25,
    "offset": 0,
    "count": 1
  }
}

total — число подходящих строк, count — число строк на этой странице.

Ошибка

Ответ
{
  "error": {
    "code": "not_found",
    "message": "Member not found"
  }
}

Поле details добавляется, если ошибка несёт дополнительные сведения (например, список ошибок регистрации из POST /members).

Коды статуса

Код Значение
200 Запрос выполнен успешно, в теле — data
201 Ресурс создан
204 Запрос выполнен успешно без тела (операции DELETE)
400 Запрос некорректен или поле имеет неверное значение (bad_request)
401 Ключ отсутствует, неизвестен или принадлежит деактивированному аккаунту (unauthorized)
403 У пользователя нет прав на операцию (forbidden)
404 Ресурс или эндпоинт не существует (not_found)
405 Путь существует, но не для этого метода (method_not_allowed)
429 Срабатывает ограничение частоты от стороннего хука (too_many_requests)
500 Непредвиденная ошибка; она пишется в лог (internal_error)
503 API выключен (service_unavailable)

Заголовки

Любой ответ отправляется как Content-Type: application/json; charset=utf-8 с заголовком X-Content-Type-Options: nosniff. Дополнительные заголовки можно добавить через хук integrate_api_pre_send.

Категории

Обязательные поля

В списках полей ниже поле, помеченное как обязательное, требуется при полной замене (PUT). При создании (POST) требуются только те поля, которые проверяет сам эндпоинт — обычно имя, а для разделов ещё и родительская категория.

Поле Тип Примечание
id int id категории
name string Название
description string Описание
order int Позиция среди категорий (с нуля)
can_collapse bool Сворачивается ли категория
Метод Путь Права / примечания
GET categories Категории: управляющие форумом получают все, включая пустые, остальные — только те, в которых есть хотя бы один видимый раздел
GET categories/{id} Одна категория; в ответе есть её видимые разделы в boards
GET categories/{cat_id}/boards Разделы одной категории
POST categories manage_boards; обязательно name; ответ 201
PUT categories/{id} manage_boards; обязательны name и description
PATCH categories/{id} manage_boards; меняются только присланные поля
DELETE categories/{id} manage_boards; разделы переезжают в ?move_boards_to=<id> или удаляются вместе с категорией

Изменяемые поля: name (обязательное), description (обязательное), order, can_collapse. Вместо order принимается и имя колонки SMF cat_order.

Разделы

Поле Тип Примечание
id int id раздела
category int id родительской категории
parent int id родительского раздела, 0 для корневого
name string Название
description string Описание
num_topics int Число тем
num_posts int Число сообщений
order int Позиция среди соседних разделов (с нуля)
Метод Путь Права / примечания
GET boards Разделы, видимые пользователю
GET boards/{id} Один раздел
GET boards/{board_id}/topics Темы одного раздела
POST boards manage_boards; обязательны name и category; ответ 201
PUT boards/{id} manage_boards; обязательны name и description
PATCH boards/{id} manage_boards; меняются только присланные поля
DELETE boards/{id} manage_boards; дочерние разделы переезжают в ?move_children_to=<id> или удаляются вместе с разделом

Изменяемые поля: name (обязательное), description (обязательное), category, parent, order, id_profile, id_theme, override_theme, count_posts, member_groups, deny_member_groups, redirect. Имена колонок SMF id_cat, id_parent и board_order принимаются как псевдонимы. Родительский раздел должен быть в той же категории, что и сам раздел.

Пользователи

Поле Тип Примечание
id int id пользователя
username string Логин
name string Отображаемое имя
posts int Число сообщений
date_registered int Unix-время регистрации
last_login int Unix-время последнего входа
primary_group int id основной группы
post_group int id пост-группы
additional_groups string id дополнительных групп через запятую
email string Только для администраторов
personal_text, signature, birthdate, website_title, website_url, usertitle, avatar, show_online, time_format, timezone, time_offset, id_theme, lngfile, smiley_set, pm_receive_from, warning, ignore_boards, secret_question, is_activated — Только для администраторов и только в ответе на один ресурс
Метод Путь Права / примечания
GET members view_mlist; список активированных пользователей
GET members/{id} Один пользователь; приватные поля добавляются для администраторов
POST members moderate_forum; обязательны username и email; ответ 201
PUT members/{id} profile_identity_own для себя, profile_identity_any для других; обязательны username, name и email
PATCH members/{id} Те же права; меняются только присланные поля
DELETE members/{id} profile_remove_own для себя, profile_remove_any для других; администратора удаляет только администратор

Изменяемые поля: username (обязательное), name (обязательное), email (обязательное), password, primary_group, post_group, additional_groups, posts, personal_text, signature, birthdate, website_title, website_url, usertitle, avatar, show_online, time_format, timezone, time_offset, id_theme, lngfile, smiley_set, pm_receive_from, warning, ignore_boards, is_activated, secret_question, secret_answer. Имена колонок SMF member_name, real_name, email_address, passwd, id_group и id_post_group принимаются как псевдонимы.

Смена групп требует manage_membergroups; смена posts, warning, is_activated, secret_question или secret_answer — moderate_forum. Смена пароля другого пользователя — moderate_forum.

Группы пользователей

Поле Тип Примечание
id int id группы
name string Название
description string Описание
type int 0 приватная, 1 защищённая, 2 запрашиваемая, 3 свободная
min_posts int Порог постов; -1 означает «не по пост-критерию»
max_messages int Лимит сообщений
color string Цвет группы в списке пользователей онлайн
icons string Иконки группы
hidden int 1, если группа скрыта
parent int id родительской группы
tfa_required bool Требуется ли двухфакторная аутентификация
Метод Путь Права / примечания
GET groups Скрытые группы видны только при manage_membergroups, группа модераторов — только администраторам
GET groups/{id} Одна группа с теми же правилами видимости
POST groups manage_membergroups; обязательно name; ответ 201
PUT groups/{id} manage_membergroups; обязательны name, description, type, min_posts и max_messages
PATCH groups/{id} manage_membergroups; меняются только присланные поля
DELETE groups/{id} manage_membergroups; группа, используемая платной подпиской, удалению не подлежит

Изменяемые поля: name (обязательное), description (обязательное), type (обязательное), min_posts (обязательное), max_messages (обязательное), color, icons, hidden, parent, tfa_required. Имена колонок SMF group_name, group_type, online_color и id_parent принимаются как псевдонимы. Защищённые группы (type = 1) может создавать, менять и удалять только администратор.

Темы

Поле Тип Примечание
id int id темы
board int id раздела
subject string Заголовок первого сообщения
starter object id и name автора темы
poster_time int Unix-время первого сообщения
num_replies int Число ответов
num_views int Число просмотров
locked bool Закрыта ли тема
is_sticky bool Закреплена ли тема
approved bool Одобрена ли тема
id_first_msg, id_last_msg int id первого и последнего сообщений
body, body_raw string Только в ответе на один ресурс: разобранный и исходный текст
Метод Путь Права / примечания
GET topics Темы всех видимых разделов; не-администраторы видят только одобренные
GET topics/{id} Одна тема вместе с текстом
GET boards/{board_id}/topics Темы одного раздела
POST topics post_new в целевом разделе; обязательны board, subject и body; ответ 201
PUT topics/{id} modify_own / modify_any; обязательно subject
PATCH topics/{id} Те же права; меняются только присланные поля
DELETE topics/{id} remove_own / remove_any; корзина учитывается

Изменяемые поля: subject (обязательное), body, locked, is_sticky, approved, num_views, board. Имена колонок SMF sticky и id_board принимаются как псевдонимы. Закрытие требует lock_own / lock_any, закрепление — make_sticky, одобрение — approve_posts, смена счётчика просмотров — moderate_board.

Сообщения

Поле Тип Примечание
id int id сообщения
topic int id темы
board int id раздела
subject string Заголовок
author object id, name и email автора
poster_time int Unix-время
modified_time, modified_name, modified_reason — Отметка о правке
icon string Иконка сообщения
smileys_enabled bool Включены ли смайлы
approved bool Одобрено ли сообщение
body, body_raw string Разобранный и исходный текст
Метод Путь Права / примечания
GET posts/{id} Одно сообщение; не-администраторы видят только одобренные
GET topics/{topic_id}/posts Сообщения одной темы
POST posts post_reply_any / post_reply_own; в теле — topic и body; ответ 201
PUT posts/{id} modify_own / modify_any; обязательно body
PATCH posts/{id} Те же права; меняются только присланные поля
DELETE posts/{id} delete_own / delete_any; первое сообщение темы, у которой ещё есть ответы, удалить нельзя

Изменяемые поля: body (обязательное), subject, icon, smileys_enabled, approved, poster_name, poster_email, poster_time, modified_reason. Имя колонки SMF reason принимается как псевдоним для modified_reason. Смена poster_name, poster_email или poster_time требует moderate_forum, одобрение сообщения — approve_posts.

Ответ указывает тему в теле

POST /posts — единственный эндпоинт, который берёт родителя из тела запроса, а не из пути: id темы передаётся полем topic. Путь вида /topics/{topic_id}/posts столкнулся бы с зарезервированным query-параметром SMF topic.

Маршруты сторонних модов

Маршруты, зарегистрированные другими модами, адресуются так же, как встроенные: префикс версии остаётся частью URL, а в паттерне маршрута его нет:

index.php?action=api&path=v1/widgets

Пример регистрации — в разделе Добавление ресурса.