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

Расширение 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(), — могут её проверить и подстроиться, вместо того чтобы считать, что браузер ждёт редиректа:

post handler
<?php declare(strict_types=1);

if (defined('SMF_API_REQUEST')) {
    // Запрос пришёл из API: отвечаем JSON, а не редиректом.
}

Сам мод использует это так: если установлен мод Merge Double Posts, его редирект прервал бы запрос до вывода JSON, поэтому для запросов к API мод отключает слияние — и каждый POST создаёт отдельное сообщение с предсказуемым id.