Расширение SMF RESTful API — Обзор и хуки¶
API спроектирован так, чтобы сторонние моды могли добавлять свои ресурсы и влиять на обработку запросов через хуки, которые вызывает сам мод — не изменяя файлы этого мода.
Доступные хуки¶
Эти четыре хука созданы самим модом: в штатном SMF таких нет, мод вызывает их для стороннего кода. Свои обработчики регистрируйте через add_integration_function() так же, как для любого хука SMF.
| Хук | Описание | Когда вызывается |
|---|---|---|
integrate_api_routes (Router $router) |
Регистрация своих эндпоинтов | При инициализации маршрутизатора |
integrate_api_pre_dispatch (Request $request) |
Глобальная логика (throttle, CORS-preflight); может бросить ApiException |
После разбора запроса, до аутентификации |
integrate_api_authenticate (Request $request, ?int &$idMember) |
Свои схемы (OAuth/JWT): выставьте $idMember |
В начале аутентификации |
integrate_api_pre_send (mixed &$payload, int &$status, array &$headers) |
Правка тела, статуса и заголовков (CORS, rate-limit, обёртки) | Перед выводом ответа |
Откуда берутся хуки¶
Мод вызывает call_integration_hook() с этими именами, поэтому любой мод может подписаться на них через add_integration_function() — тем же механизмом, которым пользуется сам SMF. Пример регистрации — в разделе Добавление ресурса.
Префикс версии и стиль маршрутов¶
Маршруты регистрируются без префикса версии. Ведущий сегмент версии (v1) снимает и проверяет сам Router, поэтому паттерны остаются версия-агностичными. Клиент обращается к ресурсу как index.php?action=api&path=v1/widgets. См. Добавление ресурса про вложенные коллекции и зарезервированные имена параметров.
Как отличить вызовы API¶
Пока обрабатывается запрос к API, определена константа SMF_API_REQUEST. Хуки, которые срабатывают глубоко внутри SMF — например, внутри createPost(), — могут её проверить и подстроиться, вместо того чтобы считать, что браузер ждёт редиректа:
<?php declare(strict_types=1);
if (defined('SMF_API_REQUEST')) {
// Запрос пришёл из API: отвечаем JSON, а не редиректом.
}
Сам мод использует это так: если установлен мод Merge Double Posts, его редирект прервал бы запрос до вывода JSON, поэтому для запросов к API мод отключает слияние — и каждый POST создаёт отдельное сообщение с предсказуемым id.