Начало работы¶
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.