REST API Patterns
How register_rest_route maps to Siren's controller, middleware, and validation system.
WordPress plugin
Last updated: October 26, 2026
In WordPress, you register REST routes with register_rest_route, passing a namespace, a path, and an array of methods, callbacks, and permission callbacks. Siren replaces this with controller classes that implement typed interfaces for routing, middleware, and validation.
// WordPress: register a REST route with inline callbacks
add_action('rest_api_init', function () {
register_rest_route('my-plugin/v1', '/items', [
'methods' => 'GET',
'callback' => function (WP_REST_Request $request) {
$items = get_posts(['post_type' => 'item']);
return rest_ensure_response($items);
},
'permission_callback' => function () {
return current_user_can('manage_options');
},
]);
}); // Siren: a controller class with middleware and validation
use PHPNomad\Auth\Enums\ActionTypes;
use PHPNomad\Auth\Interfaces\CurrentContextResolverStrategy;
use PHPNomad\Auth\Services\AuthPolicyEvaluatorService;
use PHPNomad\Auth\Traits\CanCreateAuthMiddlewareFromCurrentContext;
use PHPNomad\Http\Enums\Method;
use PHPNomad\Http\Interfaces\Request;
use PHPNomad\Http\Interfaces\Response;
use PHPNomad\Rest\Factories\ValidationSet;
use PHPNomad\Rest\Interfaces\Controller;
use PHPNomad\Rest\Interfaces\HasMiddleware;
use PHPNomad\Rest\Interfaces\HasValidations;
use PHPNomad\Rest\Middleware\ValidationMiddleware;
use Siren\Programs\Core\Datastores\Program\Interfaces\ProgramDatastore;
use Siren\Programs\Core\Models\Adapters\ProgramAdapter;
use Siren\Programs\Core\Models\Program;
use Siren\Validations\Core\IsOneOf;
class ListProgramsController implements Controller, HasMiddleware, HasValidations
{
use CanCreateAuthMiddlewareFromCurrentContext;
// The trait reads $currentContextResolver and $authPolicyEvaluatorService,
// so the constructor has to inject both.
public function __construct(
protected ProgramDatastore $programs,
protected ProgramAdapter $adapter,
protected Response $response,
protected CurrentContextResolverStrategy $currentContextResolver,
protected AuthPolicyEvaluatorService $authPolicyEvaluatorService
) {}
public function getMethod(): string
{
return Method::Get;
}
public function getEndpoint(): string
{
return '/my-plugin/programs';
}
public function getMiddleware(Request $request): array
{
return [
// Auth middleware checks permissions before getResponse() runs
$this->createAuthMiddlewareFromCurrentContext(ActionTypes::Read, Program::class),
// Runs the rules from getValidations()
new ValidationMiddleware($this),
];
}
public function getValidations(): array
{
return [
'status' => (new ValidationSet())
->addValidation(fn() => new IsOneOf(['active', 'inactive', 'draft'])),
];
}
public function getResponse(Request $request): Response
{
$programs = $this->programs->andWhere([
['column' => 'status', 'operator' => '=', 'value' => $request->getParam('status') ?? 'active'],
]);
return $this->response
->setStatus(200)
->setJson(array_map(fn(Program $program) => $this->adapter->toArray($program), $programs));
}
} How do controllers register?
Controllers are registered via the HasControllers interface on an initializer. This is analogous to calling register_rest_route inside a rest_api_init callback, but declarative:
use PHPNomad\Rest\Interfaces\HasControllers;
class MyInitializer implements HasControllers
{
public function getControllers(): array
{
return [
ListProgramsController::class,
GetProgramController::class,
UpdateProgramController::class,
];
}
}
The framework resolves each controller from the DI container (so constructor injection works), then registers the route based on getMethod() and getEndpoint(). On WordPress, the endpoint sits under Siren’s REST namespace, so the sample above answers at /wp-json/siren/v1/my-plugin/programs.
How does the middleware chain work?
Middleware runs before your controller’s getResponse() method, in the order you declare it. This replaces WordPress’s permission_callback with a composable chain:
- Authentication middleware verifies the user is logged in and has a valid token
- Validation middleware checks request parameters against your validation rules
- Owner scoping middleware restricts results to records the current user owns (for collaborator-facing endpoints)
- Your handler runs only if all middleware passes
If any middleware rejects the request, the chain stops and an error response is returned. Validation failures return 400 with field-level errors. The middleware from createAuthMiddlewareFromCurrentContext() refuses with 400 and “You don’t have permission to do that.” On WordPress, a 401 or 403 thrown by middleware becomes WordPress’s {code, message, data} error, with rest_not_logged_in or rest_forbidden. To refuse that way, write a middleware that throws with the status, as Error Handling shows.
What about validation?
WordPress REST route validation uses validate_callback and sanitize_callback on individual args. A Siren controller implements HasValidations and returns an array from getValidations(), keyed by field name, with a ValidationSet for each field. setRequired() marks a field as required, and addValidation() adds a rule, as the status rule in the sample above shows. The rules run only when getMiddleware() includes new ValidationMiddleware($this).
When validation fails, the framework throws a ValidationException that the REST layer converts to a 400 response with field-level error details. You do not need to manually check parameters in your handler.
Why is there no facade shortcut for controllers?
Controllers are always registered through the DI system. Unlike events or config, there is no facade for REST route registration. This is intentional. Controllers depend on middleware, validation, and the full request/response lifecycle, which requires proper DI wiring. Facades are useful for simple lookups, but REST endpoints involve too many moving parts for a static wrapper to be practical.
Where to go next
For the full REST API conventions (route naming, response formats, pagination parameters, and CRUD patterns), see the Resource Reference Introduction.
For the full PHPNomad framework documentation on REST, see REST.