playbooks

home / skills / automattic / agent-skills / wp-rest-api

wp-rest-api skill

/skills/wp-rest-api

This skill helps you create, debug, and extend WordPress REST API endpoints, ensuring proper authentication, validation, and data shaping.

npx playbooks add skill automattic/agent-skills --skill wp-rest-api

Review the files below or copy the command above to add this skill to your agents.

Files (7)
SKILL.md
4.8 KB
---
name: wp-rest-api
description: "Use when building, extending, or debugging WordPress REST API endpoints/routes: register_rest_route, WP_REST_Controller/controller classes, schema/argument validation, permission_callback/authentication, response shaping, register_rest_field/register_meta, or exposing CPTs/taxonomies via show_in_rest."
compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
---

# WP REST API

## When to use

Use this skill when you need to:

- create or update REST routes/endpoints
- debug 401/403/404 errors or permission/nonce issues
- add custom fields/meta to REST responses
- expose custom post types or taxonomies via REST
- implement schema + argument validation
- adjust response links/embedding/pagination

## Inputs required

- Repo root + target plugin/theme/mu-plugin (path to entrypoint).
- Desired namespace + version (e.g. `my-plugin/v1`) and routes.
- Authentication mode (cookie + nonce vs application passwords vs auth plugin).
- Target WordPress version constraints (if below 6.9, call out).

## Procedure

### 0) Triage and locate REST usage

1. Run triage:
   - `node skills/wp-project-triage/scripts/detect_wp_project.mjs`
2. Search for existing REST usage:
   - `register_rest_route`
   - `WP_REST_Controller`
   - `rest_api_init`
   - `show_in_rest`, `rest_base`, `rest_controller_class`

If this is a full site repo, pick the specific plugin/theme before changing code.

### 1) Choose the right approach

- **Expose CPT/taxonomy in `wp/v2`:**
  - Use `show_in_rest => true` + `rest_base` if needed.
  - Optionally provide `rest_controller_class`.
  - Read `references/custom-content-types.md`.
- **Custom endpoints:**
  - Use `register_rest_route()` on `rest_api_init`.
  - Prefer a controller class (`WP_REST_Controller` subclass) for anything non-trivial.
  - Read `references/routes-and-endpoints.md` and `references/schema.md`.

### 2) Register routes safely (namespaces, methods, permissions)

- Use a unique namespace `vendor/v1`; avoid `wp/*` unless core.
- Always provide `permission_callback` (use `__return_true` for public endpoints).
- Use `WP_REST_Server::READABLE/CREATABLE/EDITABLE/DELETABLE` constants.
- Return data via `rest_ensure_response()` or `WP_REST_Response`.
- Return errors via `WP_Error` with an explicit `status`.

Read `references/routes-and-endpoints.md`.

### 3) Validate/sanitize request args

- Define `args` with `type`, `default`, `required`, `validate_callback`, `sanitize_callback`.
- Prefer JSON Schema validation with `rest_validate_value_from_schema` then `rest_sanitize_value_from_schema`.
- Never read `$_GET`/`$_POST` directly inside endpoints; use `WP_REST_Request`.

Read `references/schema.md`.

### 4) Responses, fields, and links

- Do **not** remove core fields from default endpoints; add fields instead.
- Use `register_rest_field` for computed fields; `register_meta` with `show_in_rest` for meta.
- For `object`/`array` meta, define schema in `show_in_rest.schema`.
- If you need unfiltered post content (e.g., ToC plugins injecting HTML), request `?context=edit` to access `content.raw` (auth required). Pair with `_fields=content.raw` to keep responses small.
- Add related resource links via `WP_REST_Response::add_link()`.

Read `references/responses-and-fields.md`.

### 5) Authentication and authorization

- For wp-admin/JS: cookie auth + `X-WP-Nonce` (action `wp_rest`).
- For external clients: application passwords (basic auth) or an auth plugin.
- Use capability checks in `permission_callback` (authorization), not just “logged in”.

Read `references/authentication.md`.

### 6) Client-facing behavior (discovery, pagination, embeds)

- Ensure discovery works (`Link` header or `<link rel="https://api.w.org/">`).
- Support `_fields`, `_embed`, `_method`, `_envelope`, pagination headers.
- Remember `per_page` is capped at 100.

Read `references/discovery-and-params.md`.

## Verification

- `/wp-json/` index includes your namespace.
- `OPTIONS` on your route returns schema (when provided).
- Endpoint returns expected data; permission failures return 401/403 as appropriate.
- CPT/taxonomy routes appear under `wp/v2` when `show_in_rest` is true.
- Run repo lint/tests and any PHP/JS build steps.

## Failure modes / debugging

- 404: `rest_api_init` not firing, route typo, or permalinks off (use `?rest_route=`).
- 401/403: missing nonce/auth, or `permission_callback` too strict.
- `_doing_it_wrong` for missing `permission_callback`: add it (use `__return_true` if public).
- Invalid params: missing/incorrect `args` schema or validation callbacks.
- Fields missing: `show_in_rest` false, meta not registered, or CPT lacks `custom-fields` support.

## Escalation

If version support or behavior is unclear, consult the REST API Handbook and core docs before inventing patterns.

Overview

This skill helps build, extend, and debug WordPress REST API endpoints and routes. It covers registering routes, controller classes, schema/argument validation, permission checks, response shaping, and exposing custom post types and taxonomies via show_in_rest. Use it to make endpoints robust, secure, and discoverable.

How this skill works

I inspect the repository for rest_api_init usage, register_rest_route calls, WP_REST_Controller subclasses, and show_in_rest flags to locate existing REST logic. I recommend patterns: exposing CPTs via show_in_rest, creating custom routes on rest_api_init, using controller classes for non-trivial endpoints, and defining args schemas with validate/sanitize callbacks. I also verify authentication, permissions, response shaping (register_rest_field/register_meta), and discovery/pagination behavior.

When to use it

  • Adding or updating REST routes and controller logic
  • Debugging 401/403/404 errors, missing nonces, or permission issues
  • Adding custom fields or meta to REST responses
  • Exposing custom post types or taxonomies via show_in_rest
  • Implementing schema and argument validation for endpoint inputs

Best practices

  • Use a unique namespace like vendor/v1; avoid colliding with wp/*
  • Always provide a permission_callback; use capability checks for auth
  • Define args with type/default/required and validate/sanitize callbacks or JSON Schema
  • Return responses with rest_ensure_response() and errors as WP_Error with status
  • Prefer controller classes for complex endpoints and register_meta/show_in_rest for meta

Example use cases

  • Expose a custom post type to wp/v2 by setting show_in_rest and a rest_base
  • Create a search endpoint with a WP_REST_Controller subclass and paginated responses
  • Add a computed field to post responses using register_rest_field and a callback
  • Debug a 403 from missing X-WP-Nonce in admin AJAX by checking cookie auth flow
  • Validate complex JSON input using rest_validate_value_from_schema and schema defs

FAQ

Why do I get 404 for my custom route?

Check that rest_api_init runs (correct hook and plugin loaded), verify the route namespace/method, and test with ?rest_route= to bypass permalinks.

How should I handle authentication for external clients?

Use application passwords or an auth plugin for external clients; for admin JS use cookie auth with X-WP-Nonce and capability checks in permission_callback.