# Расширение 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. Пример регистрации — в разделе [Добавление ресурса](<https://dragomano.github.io/SMF-RESTful-API/ru/guide/extending/adding-resource/index.md>).

## Префикс версии и стиль маршрутов

Маршруты регистрируются *без* префикса версии. Ведущий сегмент версии (`v1`) снимает и проверяет сам `Router`, поэтому паттерны остаются версия-агностичными. Клиент обращается к ресурсу как `index.php?action=api&path=v1/widgets`. См. [Добавление ресурса](<https://dragomano.github.io/SMF-RESTful-API/ru/guide/extending/adding-resource/index.md>) про вложенные коллекции и зарезервированные имена параметров.

## Как отличить вызовы API

Пока обрабатывается запрос к API, определена константа `SMF_API_REQUEST`. Хуки, которые срабатывают глубоко внутри SMF — например, внутри `createPost()`, — могут её проверить и подстроиться, вместо того чтобы считать, что браузер ждёт редиректа:

post handler

```php
<?php declare(strict_types=1);

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

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