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

• Run triage:

• node skills/wp-project-triage/scripts/detect_wp_project.mjs

• 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.