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/detectwpproject.mjs

1. Search for existing REST usage:

- registerrestroute - WPRESTController - restapiinit - showinrest, restbase, restcontroller_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 showinrest => true + restbase if needed. - Optionally provide restcontroller_class. - Read references/custom-content-types.md.

• Custom endpoints:

- Use registerrestroute() on restapiinit. - Prefer a controller class (WPRESTController 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 WPRESTServer::READABLE/CREATABLE/EDITABLE/DELETABLE constants.
• Return data via restensureresponse() or WPRESTResponse.
• 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, validatecallback, sanitizecallback.
• Prefer JSON Schema validation with restvalidatevaluefromschema then restsanitizevaluefromschema.
• Never read $GET/$POST directly inside endpoints; use WPRESTRequest.

Read references/schema.md.

4) Responses, fields, and links

• Do not remove core fields from default endpoints; add fields instead.
• Use registerrestfield for computed fields; registermeta with showin_rest for meta.
• For object/array meta, define schema in showinrest.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 WPRESTResponse::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 showinrest is true.
• Run repo lint/tests and any PHP/JS build steps.

Failure modes / debugging

• 404: restapiinit not firing, route typo, or permalinks off (use ?rest_route=).
• 401/403: missing nonce/auth, or permission_callback too strict.
• doingitwrong for missing permissioncallback: add it (use __return_true if public).
• Invalid params: missing/incorrect args schema or validation callbacks.
• Fields missing: showinrest 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.