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

Начало работы

SMF RESTful API — модификация для форума SMF 2.1, добавляющая поверх движка полноценный REST-интерфейс с ответами в формате JSON. Мод регистрирует единственное действие index.php?action=api и передаёт запрос собственному маршрутизатору. Обращение к ресурсу выглядит как index.php?action=api;path=v1/members/5, а при настроенном правиле перезаписи — как /api/v1/members/5.

Полный список эндпоинтов — методы, пути, права, изменяемые поля и коды ошибок — собра в разделе Справочник API.

Включение API

Мод поставляется выключенным. Откройте «Админка → Конфигурация → Настройки модов → RESTful API» и:

  • включите «Включить API» — пока мод выключен, любой эндпоинт отвечает 503 Service Unavailable;
  • добавьте API-ключи: каждый ключ — непрозрачный токен, привязанный к id пользователя, и любой запрос с этим ключом выполняется с правами этого пользователя. Страница умеет сама сгенерировать случайный токен.
Первый запрос
curl -H 'Authorization: Bearer YOUR_KEY' \
     'https://forum.example.com/index.php?action=api;path=v1/members/5'

Работать через API могут только полностью активированные аккаунты (is_activated = 1).

Ресурсы и операции

Из коробки доступны ресурсы categories, members, groups, boards, topics и posts с операциями чтения (GET) и изменения (POST / PUT / PATCH / DELETE).

  • Чтение идёт через лёгкий построитель запросов Query с учётом видимости разделов ({query_see_board}) и постраничной выдачей.
  • Запись — через штатные функции SMF (createBoard, modifyBoard, deleteBoards и т. п.), поэтому права и бизнес-логика ядра соблюдаются.
  • Клиент аутентифицируется по API-ключу (заголовок Authorization: Bearer ..., X-API-Key или параметр api_key), после чего мод восстанавливает полный контекст пользователя SMF ($user_info, права, allowedTo(), {query_see_board}) — ровно как для авторизованной сессии в браузере.

Все коллекции постраничные: limit (1–100, по умолчанию 25) и offset. В любом ответе ресурс лежит в data, а у коллекций к нему добавляются метаданные пагинации в meta.

Список эндпоинтов — в разделе Справочник API, подробности аутентификации и свои схемы — в разделе Свои схемы аутентификации.

Как работает маршрутизация

  • Мод открывает единственное действие SMF action=api.
  • Параметр path несёт путь к ресурсу, например v1/members/5. При включённых rewrite-правилах ведущий сегмент api снимается автоматически и остаток попадает в path.
  • Router снимает и проверяет ведущий сегмент версии (v1), поэтому шаблоны маршрутов версия-агностичны. Сейчас поддерживается только v1. Query-параметры вроде ?limit=25&offset=50 сохраняются.
  • Поддерживаются GET, POST, PUT, PATCH и DELETE. Клиенты, которые умеют отправлять только GET и POST, могут переопределить метод заголовком X-HTTP-Method-Override или query-параметром _method.

См. Чистые URL с правилами перезаписи.

Формат запроса и ответа

  • Тело запроса читается как JSON, если заголовок Content-Type содержит application/json; иначе используется обычная form-encoded полезная нагрузка.
  • Один ресурс возвращается как {"data": {...}}, коллекция — как {"data": [...], "meta": {"total": 42, "limit": 25, "offset": 0, "count": 1}}, ошибка — как {"error": {"code": "not_found", "message": "Member not found"}}.

Только хуки и настройки

Мод не редактирует файлы ядра (работает только через хуки), а ключи задаются на странице «Админка → Конфигурация → Настройки модов → RESTful API».

Сторонние моды могут расширять API — регистрировать свои маршруты и схемы аутентификации, править ответы — через интеграционные хуки. Подробно это описано в разделе Расширение API.