# Getting Started

*SMF RESTful API* is a modification for [SMF 2.1](<https://github.com/SimpleMachines/SMF2.1>) that layers a full-featured REST interface with JSON responses on top of the engine. The mod registers a single action, `index.php?action=api`, and passes the request to its own router. A resource is addressed as `index.php?action=api;path=v1/members/5`, or, with a rewrite rule in place, as `/api/v1/members/5`.

The full endpoint list — methods, paths, permissions, writable fields and error codes — is in the [API Reference](<https://dragomano.github.io/SMF-RESTful-API/guide/api-reference/index.md>).

## Enabling the API

The mod ships switched off. Open *Admin → Configuration → Modification Settings → RESTful API* and:

- tick **Enable the API** — while it is off every endpoint answers `503 Service Unavailable`;
- add API keys: each key is an opaque token bound to a member id, and every request made with that key acts with that member's permissions. The page can generate a random token for you.

First request

```bash
curl -H 'Authorization: Bearer YOUR_KEY' \
     'https://forum.example.com/index.php?action=api;path=v1/members/5'
```

Only fully activated accounts (`is_activated = 1`) can drive the API.

## Resources and operations

Out of the box you get the `categories`, `members`, `groups`, `boards`, `topics`, and `posts` resources with read (`GET`) and write (`POST` / `PUT` / `PATCH` / `DELETE`) operations.

- Reads go through a lightweight `Query` builder that respects board visibility (`{query_see_board}`) and paginates results.
- Writes go through SMF's native functions (`createBoard`, `modifyBoard`, `deleteBoards`, and so on), so the core's permissions and business logic are honored.
- The client authenticates with an API key (the `Authorization: Bearer ...` header, `X-API-Key`, or the `api_key` parameter), after which the mod restores the full SMF user context (`$user_info`, permissions, `allowedTo()`, `{query_see_board}`) — exactly as it would for an authenticated browser session.

Every collection is paginated with `limit` (1–100, default 25) and `offset`; every answer carries the resource in `data` and, for collections, pagination metadata in `meta`.

See [API Reference](<https://dragomano.github.io/SMF-RESTful-API/guide/api-reference/index.md>) for the endpoints and [Custom Authentication](<https://dragomano.github.io/SMF-RESTful-API/guide/extending/authentication/index.md>) for the full authentication flow and custom schemes.

## How routing works

- The mod exposes a single SMF action `action=api`.
- The `path` parameter carries the resource path, e.g. `v1/members/5`. When clean-URL rewrites are enabled, the leading `api` segment is stripped automatically and the rest lands in `path`.
- The `Router` strips and validates the leading version segment (`v1`), so route patterns are version-agnostic. Only `v1` is supported at the moment. Query parameters such as `?limit=25&offset=50` are preserved.
- `GET`, `POST`, `PUT`, `PATCH` and `DELETE` are supported. Clients that cannot send verbs other than `GET` and `POST` may override the method with the `X-HTTP-Method-Override` header or the `_method` query parameter.

See [Clean URLs](<https://dragomano.github.io/SMF-RESTful-API/guide/clean-urls/index.md>) for rewrite rules.

## Request and response format

- The request body is read as JSON when the `Content-Type` header contains `application/json`; otherwise the ordinary form-encoded payload is used.
- A single resource is returned as `{"data": {...}}`, a collection as `{"data": [...], "meta": {"total": 42, "limit": 25, "offset": 0, "count": 1}}`, and a failure as `{"error": {"code": "not_found", "message": "Member not found"}}`.

## Hooks-only and settings

The mod does not edit core files (it works only through hooks), and keys are set on the "Admin → Configuration → Modification Settings → RESTful API" page.

Third-party mods can extend the API — register their own routes and authentication schemes, tweak responses — through integration hooks. How to do this is described in detail under [Extending the API](<https://dragomano.github.io/SMF-RESTful-API/guide/extending/overview/index.md>).
