superpowers-sage:wp-rest-api

WordPress REST API Patterns

When to use

Use this skill when the task involves creating, modifying, or debugging WordPress REST API endpoints, or when deciding between native REST and Acorn Routes for an API surface.

Inputs required

• The API requirements: what data to expose, who consumes it, and authentication needs
• Whether the project already uses Acorn Routes (check routes/web.php or routes/api.php)
• The target consumers: Gutenberg editor, mobile apps, third-party integrations, or internal front-end

Procedure

Step 1 — Choose between Native REST and Acorn Routes

See references/acorn-coexistence.md for the full decision matrix.

Quick rule: use native REST for WordPress-ecosystem integration and Acorn Routes for application logic. Both can coexist in the same project.

Step 2 — Register native REST endpoints

Always use register_rest_route() inside a rest_api_init action. Never omit permission_callback.

See references/custom-endpoints.md for full examples including WP_REST_Controller pattern and JSON schema validation.

public function boot(): void
{
    add_action('rest_api_init', [$this, 'registerRoutes']);
}

public function registerRoutes(): void
{
    register_rest_route('myapp/v1', '/posts', [
        'methods'             => 'GET',
        'callback'            => [$this, 'getPosts'],
        'permission_callback' => '__return_true',
    ]);

    register_rest_route('myapp/v1', '/posts', [
        'methods'             => 'POST',
        'callback'            => [$this, 'createPost'],
        'permission_callback' => fn() => current_user_can('edit_posts'),
        'args'                => $this->getCreatePostArgs(),
    ]);
}

Step 3 — Authentication

See references/authentication.md for Application Passwords, cookie/nonce auth, and JWT patterns.

Quick reference:

• Same-origin JS: Cookie + X-WP-Nonce header
• External app / mobile: Application Passwords (Basic Auth)
• Internal Acorn routes: JWT middleware with wp_set_current_user()