Getting Started¶
SMF RESTful API is a modification for SMF 2.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.
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.
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
Querybuilder 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 theapi_keyparameter), 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 for the endpoints and Custom Authentication for the full authentication flow and custom schemes.
How routing works¶
- The mod exposes a single SMF action
action=api. - The
pathparameter carries the resource path, e.g.v1/members/5. When clean-URL rewrites are enabled, the leadingapisegment is stripped automatically and the rest lands inpath. - The
Routerstrips and validates the leading version segment (v1), so route patterns are version-agnostic. Onlyv1is supported at the moment. Query parameters such as?limit=25&offset=50are preserved. GET,POST,PUT,PATCHandDELETEare supported. Clients that cannot send verbs other thanGETandPOSTmay override the method with theX-HTTP-Method-Overrideheader or the_methodquery parameter.
See Clean URLs for rewrite rules.
Request and response format¶
- The request body is read as JSON when the
Content-Typeheader containsapplication/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.