Your WordPress REST API deserves controllers, not a 600-line functions.php. Here is how to get there with PHP 8 attributes.

The WordPress REST API is one of the best things that happened to WordPress. It powers the block editor, headless front-ends in Next.js or Nuxt, mobile apps and countless integrations.

Adding your own endpoints, though, has not changed much since 2016. You call register_rest_route(), pass an array of options, write a callback that reads $request->get_param() by hand, and remember to add a permission_callback. For two endpoints, that is fine. For thirty, it becomes a long file of nested arrays that nobody wants to touch.

In this article, we will build a small API for documents twice: first the native way, then with PHP 8 attributes using wp-module-rest-api, an open-source package I maintain. By the end, each endpoint will be a typed method in a plain PHP class.

You will need PHP 8.1+, Composer, and a WordPress install that loads Composer's autoloader. A Bedrock project is perfect, but a mu-plugin with its own vendor/ works too.

The native way

Our API needs two endpoints: read a document and delete it. Reading is public; deleting is reserved to administrators. With plain WordPress, it looks like this:

add_action('rest_api_init', function () { register_rest_route('app/v1', '/documents/(?P<id>\d+)', [ [ 'methods' => 'GET', 'callback' => function (\WP_REST_Request $request) { $document = get_post((int) $request->get_param('id')); if (!$document instanceof \WP_Post) { return new \WP_Error('not-found', 'Document not found.', ['status' => 404]); } return new \WP_REST_Response([ 'id' => $document->ID, 'title' => $document->post_title, ]); }, 'permission_callback' => '__return_true', ], [ 'methods' => 'DELETE', 'callback' => function (\WP_REST_Request $request) { $deleted = wp_delete_post((int) $request->get_param('id'), true); return new \WP_REST_Response(['deleted' => (bool) $deleted]); }, 'permission_callback' => fn () => current_user_can('administrator'), ], ]); }); 

It works, but look at what it costs:

• Everything is an array. Your IDE cannot autocomplete the keys, and a typo in permission_callback fails silently.
• Parameters are untyped. Every callback starts with $request->get_param() and a manual cast.
• Security is opt-in. Forget permission_callback and your endpoint is public. WordPress only logs a notice.
• Errors are ad hoc. Each callback builds its own WP_Error, with its own codes and status.
• It does not scale. Thirty endpoints means thirty of these blocks, usually in one file.

Of course, this code can be refactored: move the callbacks into classes, share the permission checks in functions, write a small helper around register_rest_route(). It helps, but the core issue remains: every endpoint is still a configuration array to write and maintain next to the code that does the work, and the whole thing stays verbose.

Setting up the attribute-based approach

Install the package with Composer:

composer require dbout/wp-module-rest-api 

Routes are discovered from a PSR-4 namespace, so make sure your composer.json autoloads your code:

{ "autoload": { "psr-4": { "App\\": "src/" } } } 

Then register the loader once, early in the WordPress boot. A mu-plugin is a good place:

<?php // wp-content/mu-plugins/api.php require __DIR__ . '/../../vendor/autoload.php'; use Dbout\WpRestApi\NamespaceRouteLoader; (new NamespaceRouteLoader('App\\Routes\\'))->register(); 

Adjust the path to vendor/autoload.php to your project layout. Every class under App\Routes\ is now scanned for routes, and register() hooks into rest_api_init for you.

Your first controller

Create src/Routes/DocumentController.php:

<?php namespace App\Routes; use Dbout\WpRestApi\Attributes\Action; use Dbout\WpRestApi\Attributes\Route; use Dbout\WpRestApi\Enums\Method; #[Route('app/v1', '/documents/(?P<id>\d+)')] class DocumentController { #[Action(Method::GET)] public function get(int $id): \WP_REST_Response { $document = get_post($id); return new \WP_REST_Response([ 'id' => $document?->ID, 'title' => $document?->post_title, ]); } #[Action(Method::DELETE)] public function delete(int $id): \WP_REST_Response { return new \WP_REST_Response([ 'deleted' => (bool) wp_delete_post($id, true), ]); } } 

That is the whole registration. GET and DELETE /wp-json/app/v1/documents/42 now hit these two methods.

A few things happen behind the scenes:

• #[Route] holds the namespace and the path, exactly as register_rest_route() expects them.
• #[Action] maps a method to one or several HTTP methods: #[Action([Method::POST, Method::PUT])] works too.
• Arguments are injected by name. The id captured by the URL is passed to $id and cast to int. The same goes for query string and body parameters.
• Need the raw request for headers or a JSON body? Add a \WP_REST_Request $request argument and you get it.

No more get_param(), no more manual casting, and your IDE understands every line. We are not done, though: right now, anyone can delete a document.

Locking it down with permissions

Permissions are declared with the same attributes. Set permissionCallback on #[Route] to protect every action of the class, or on #[Action] to protect a single one:

use Dbout\WpRestApi\Permissions\IsAdministrator; #[Action(Method::DELETE, permissionCallback: IsAdministrator::class)] public function delete(int $id): \WP_REST_Response { // Only administrators get here } 

The package ships with IsAdministrator, IsEditor, IsAuthor, IsContributor and IsSubscriber. For anything more specific, implement PermissionInterface. Here is a webhook endpoint that only accepts requests signed with a shared secret:

use Dbout\WpRestApi\Permissions\PermissionInterface; class SignaturePermission implements PermissionInterface { public function allow(\WP_REST_Request $request): bool|\WP_Error { $signature = (string) $request->get_header('signature'); $expected = hash_hmac('sha256', $request->get_body(), WEBHOOK_SECRET); return hash_equals($expected, $signature); } } 

#[Route('app/v1', '/webhooks/payment', permissionCallback: SignaturePermission::class)] class PaymentWebhookController { #[Action(Method::POST)] public function handle(\WP_REST_Request $request): \WP_REST_Response { // The signature is valid } } 

The permission lives in its own class: you can reuse it on any route and unit test it on its own. And because it is visible right on top of the class, a code review spots a missing check immediately.

Validating input with #[Param]

Let's add a list endpoint with filters. The #[Param] attribute turns method arguments into the args schema WordPress already knows how to validate:

enum Status: string { case Draft = 'draft'; case Published = 'published'; } #[Route('app/v1', '/documents')] class DocumentListController { #[Action(Method::GET)] public function list( #[Param(required: true, description: 'Category identifier')] int $category, #[Param] Status $status = Status::Published, #[Param(name: 'per_page')] int $perPage = 10, ): \WP_REST_Response { // $status is a Status instance, $perPage comes from ?per_page= } } 

From these few lines, the package builds the schema for you:

• The JSON type comes from the PHP type: int becomes integer, bool becomes boolean.
• A sanitizer is picked from the PHP type too, such as sanitize_text_field for strings.
• A backed enum restricts the accepted values to its cases, so ?status=archived is rejected.
• A missing category returns a 400 from WordPress, before your code runs.

You still write plain PHP, but you get the validation of a hand-written schema. The descriptions even show up in the /wp-json/ index, which helps whoever consumes your API.

Errors as exceptions

Our get() method still returns an empty document when the ID does not exist. Instead of building a WP_Error by hand, throw an exception:

use Dbout\WpRestApi\Exceptions\NotFoundException; #[Action(Method::GET)] public function get(int $id): \WP_REST_Response { $document = get_post($id); if (!$document instanceof \WP_Post) { throw new NotFoundException('Document'); } return new \WP_REST_Response([ 'id' => $document->ID, 'title' => $document->post_title, ]); } 

The client receives a 404 with a predictable body:

{ "error": { "code": "not-found", "message": "Document not found.", "data": [] } } 

For business errors, RouteException lets you choose the code, the HTTP status and extra data:

throw new RouteException( message: 'This document is already published.', errorCode: 'already-published', httpStatusCode: 409, ); 

And what about bugs? Any other exception returns a 500 with a generic message, so a database error never leaks into a public response. During development, a debug option shows the real message and the stack trace.

If your front-end team prefers a standard, the package also ships an RFC 7807 formatter that returns application/problem+json responses.

Ready for production

Scanning classes on every request has a cost once you have dozens of controllers. Plug in any PSR-6 cache pool and the routes are discovered once:

use Dbout\WpRestApi\NamespaceRouteLoader; use Dbout\WpRestApi\RouteLoaderOptions; use Symfony\Component\Cache\Adapter\FilesystemAdapter; $options = new RouteLoaderOptions( cache: new FilesystemAdapter(directory: WP_CONTENT_DIR . '/cache/rest-api'), debug: wp_get_environment_type() === 'development', ); (new NamespaceRouteLoader('App\\Routes\\', $options))->register(); 

Two things to keep in mind:

• Clear the cache on each deployment, otherwise new routes are ignored.
• Keep debug off in production. Stack traces are only added when both debug and WP_DEBUG are true, as a safety net.

Wrapping up

We started with nested arrays and closures, and ended with plain PHP classes:

• one controller per resource, discovered automatically through PSR-4;
• typed arguments injected by name, validated with #[Param];
• permissions declared next to the code they protect;
• errors thrown as exceptions, returned in a consistent format.

Under the hood, nothing magical happens: every route still goes through register_rest_route(). You keep the full WordPress REST API, including its index and its authentication, with a structure that holds up as your API grows.

The package is open source and MIT-licensed. The full documentation covers every option. If it saves you a few hundred lines, a star on GitHub helps other developers find it, and issues and pull requests are welcome.

composer require dbout/wp-module-rest-api 

#[Route('app/v1', '/documents/(?P<id>\d+)')] class DocumentController { #[Action(Method::GET)] public function get(int $id): \WP_REST_Response { // $id comes straight from the URL, already cast to int } }

add_action('rest_api_init', function () { register_rest_route('app/v1', '/documents/(?P<id>\d+)', [ [ 'methods' => 'GET' 'callback' => function (\WP_REST_Request $request) { $document = get_post((