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

*SMF RESTful API* — модификация для форума [SMF 2.1](<https://github.com/SimpleMachines/SMF2.1>), добавляющая поверх движка полноценный REST-интерфейс с ответами в формате JSON. Мод регистрирует единственное действие `index.php?action=api` и передаёт запрос собственному маршрутизатору. Обращение к ресурсу выглядит как `index.php?action=api;path=v1/members/5`, а при настроенном правиле перезаписи — как `/api/v1/members/5`.

Полный список эндпоинтов — методы, пути, права, изменяемые поля и коды ошибок — собра в разделе [Справочник API](<https://dragomano.github.io/SMF-RESTful-API/ru/guide/api-reference/index.md>).

## Включение API

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

- включите **«Включить API»** — пока мод выключен, любой эндпоинт отвечает `503 Service Unavailable`;
- добавьте API-ключи: каждый ключ — непрозрачный токен, привязанный к id пользователя, и любой запрос с этим ключом выполняется с правами этого пользователя. Страница умеет сама сгенерировать случайный токен.

Первый запрос

```bash
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](<https://dragomano.github.io/SMF-RESTful-API/ru/guide/api-reference/index.md>), подробности аутентификации и свои схемы — в разделе [Свои схемы аутентификации](<https://dragomano.github.io/SMF-RESTful-API/ru/guide/extending/authentication/index.md>).

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

- Мод открывает единственное действие 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](<https://dragomano.github.io/SMF-RESTful-API/ru/guide/clean-urls/index.md>) с правилами перезаписи.

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

- Тело запроса читается как 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](<https://dragomano.github.io/SMF-RESTful-API/ru/guide/extending/overview/index.md>).
