# Adding a New Resource

Below is a minimal mod that adds a `widgets` resource.

## 1\. Mod entry point

Integration.php

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

namespace Vendor\Widgets;

if (! defined('SMF'))
    die('No direct access...');

class Integration
{
    public function hooks(): void
    {
        // Your own autoloader, so SMF can find the mod's classes.
        add_integration_function('integrate_autoload', self::class . '::autoload#', false);
        add_integration_function('integrate_api_routes', self::class . '::routes#', false);
    }

    public function autoload(array &$classMap): void
    {
        $classMap['Vendor\\Widgets\\'] = 'Widgets/';
    }

    // routes() is shown in the next section
}
```

## 2\. Registering routes

The `integrate_api_routes` handler receives a `Router` object with the fluent methods `get()`, `post()`, `put()`, `patch()`, `delete()`. The `{id}` segment (or any `{name}`) is placed into the action's parameter array.

routes

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

use SMF\API\Router;

// ...

public function routes(Router $router): void
{
    $router->get('widgets', WidgetController::class, 'index');
    $router->get('widgets/{id}', WidgetController::class, 'show');
    $router->post('widgets', WidgetController::class, 'store');
}
```

The path parameters arrive as strings; validate them with `$this->id($params)` before using them in a query. Besides the verb helpers, `Router::add($method, $pattern, $class, $action)` registers a route for any other verb.

> [!NOTE]
>
> **Version prefix**
>
> Routes are registered *without* a version prefix. The leading version segment (`v1`) is stripped and validated by the `Router` itself, so the patterns stay version-agnostic. The client addresses the resource as `index.php?action=api&path=v1/widgets`.

> [!WARNING]
>
> **Nested collections and reserved parameters**
>
> Register "child" lists under the parent — `parent/{parent_id}/children`, not through a query filter. Examples from the core API: `GET boards/{board_id}/topics`, `GET categories/{cat_id}/boards`, `GET topics/{topic_id}/posts`. The reason is not just style: the names `board`, `topic`, `msg`, `start`, `action` are *SMF's reserved query parameters*. If you pass `?board=5`, the core will treat the request as a board view during `loadBoard()` and return an HTML page — it will never reach `action=api`. The parent identifier in the path (`{parent_id}`) avoids this collision; read it with `$this->id($params, 'parent_id')`.

## 3\. Controller

The controller extends `SMF\API\Controllers\AbstractController` and gets a ready-made "harness": access to the request, a response factory, the `Query` builder, pagination, and id validation.

WidgetController.php

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

namespace Vendor\Widgets;

use SMF\API\ApiException;
use SMF\API\Query;
use SMF\API\Response;
use SMF\API\Controllers\AbstractController;

if (! defined('SMF'))
    die('No direct access...');

class WidgetController extends AbstractController
{
    public function index(array $params): Response
    {
        $query = (new Query())
            ->from('{db_prefix}widgets AS w')
            ->where('w.hidden = {int:hidden}')
            ->columns('w.id_widget, w.name')
            ->orderBy('w.name')
            ->params(['hidden' => 0]);

        // Every row passes through transform();
        // a collection with pagination meta is returned.
        return $this->paginate($query);
    }

    public function show(array $params): Response
    {
        // id($params) validates {id}
        $row = $this->first(
            (new Query())
                ->from('{db_prefix}widgets')
                ->where('id_widget = {int:id}')
                ->columns('id_widget, name')
                ->params(['id' => $this->id($params)])
        );

        if ($row === null) {
            throw ApiException::notFound('Widget not found');
        }

        return $this->response()->data($this->transform($row));
    }

    protected function transform(array $row): array
    {
        return [
            'id'   => (int) $row['id_widget'],
            'name' => $row['name'],
        ];
    }
}
```

See [Query &amp; Controller](<https://dragomano.github.io/SMF-RESTful-API/guide/extending/query/index.md>) for the full reference of `Query` and `AbstractController` helpers.

> [!TIP]
>
> **What a controller action returns**
>
> An action should return a `Response` — `$this->response()->data(...)` for a single resource, `$this->paginate($query)` for a collection, `$this->noContent()` for an empty `204`. A plain array works too: the router wraps it into `data`. Anything you throw as an `ApiException` becomes a JSON error with the matching status code.
