Use this skill for inbound REST endpoints. Prefer REST for new, versioned\nplugin APIs and external clients. Keep outbound HTTP integrations out of\nthe route handlers, and use admin-ajax only for a concrete legacy or\nWP-admin-specific reason.
Read reference.md for dispatch/auth debugging, controllers,\ncollections, register_rest_field(), and edge-case verification.
Apply this order when reviewing behavior:
\nWP_REST_Server matches (namespace, route, method).permission_callback.callback only when permission succeeds.WP_Error and other supported return values into a REST response.Validation and sanitization therefore run before endpoint authorization. Keep\ntheir callbacks cheap, deterministic, read-only, and safe for anonymous traffic.
\nInventory all inbound REST surfaces:
\nrg -n \"register_rest_route|register_rest_field|rest_api_init|WP_REST_Controller\" .\nBuild a route matrix with namespace, path, method, callback, public/private\nintent, permission_callback, accepted args, and response fields.
Trace every security-sensitive identifier from its exact request source into\nthe permission check and the write/read operation. Confirm both use the same\nvalue.
\nTrace declared and undeclared input into SQL, metadata, options, filesystem,\nHTTP, email, and object update calls. Reject mass assignment.
\nVerify output field allowlists, context, pagination bounds, and stable filters.
\nTest anonymous, low-privilege, authorized, invalid-input, not-found, and\ncross-object access cases. Confirm GET/HEAD are side-effect free; for\nwrites, test method semantics and replay/retry behavior where relevant.
Report each finding with severity, route/method, file and line, exploit or\nfailure path, evidence, and the smallest correct remediation. Separate\nconfirmed exposure from defense-in-depth advice.
\nTreat unauthenticated privileged writes or sensitive reads as high/critical.\nTreat missing object-level authorization, unbounded collections, mass assignment,\nand cross-source identifier confusion as security findings, not style issues.
\nadd_action( 'rest_api_init', static function (): void {\n register_rest_route(\n 'myplugin/v1',\n '/items/(?P<id>\\d+)',\n array(\n 'methods' => WP_REST_Server::READABLE,\n 'callback' => 'myplugin_get_item',\n 'permission_callback' => static function ( WP_REST_Request $request ) {\n $url_params = $request->get_url_params();\n $post_id = (int) ( $url_params['id'] ?? 0 );\n\n return current_user_can( 'read_post', $post_id );\n },\n 'args' => array(\n 'id' => array(\n 'required' => true,\n 'type' => 'integer',\n 'minimum' => 1,\n ),\n ),\n )\n );\n} );\n\n/**\n * @return WP_REST_Response|WP_Error\n */\nfunction myplugin_get_item( WP_REST_Request $request ) {\n $url_params = $request->get_url_params();\n $post_id = (int) ( $url_params['id'] ?? 0 );\n $post = get_post( $post_id );\n\n if ( ! $post ) {\n return new WP_Error(\n 'myplugin_not_found',\n __( 'Item not found.', 'myplugin' ),\n array( 'status' => 404 )\n );\n }\n\n return rest_ensure_response(\n array(\n 'id' => $post->ID,\n 'title' => get_the_title( $post ),\n )\n );\n}\nThe exact-source lookup is intentional. Do not replace it with $request['id']\nor get_param( 'id' ) for an object identifier; merged body/query values have\nhigher priority than the URL value.
Specify permission_callback for every endpoint. Since WordPress 5.5, omitting\nit emits _doing_it_wrong(), but registration and dispatch continue. Missing or\nempty permission callbacks are skipped, so the route is open at the endpoint\npermission layer unless another layer or the main callback denies it.
Use __return_true for a deliberately public route. It is not a vulnerability\nby itself.
Never use unconditional public permission for a privileged write or sensitive\nread.
\nCheck object-level meta capabilities with the target ID:
\ncurrent_user_can( 'edit_post', $post_id );\ncurrent_user_can( 'edit_user', $user_id );\nReturn true, false, null, or WP_Error. Core denies only exact false,\nnull, or WP_Error; falsey values such as 0, '', or array() can grant\naccess. Prefer explicit true or a namespaced WP_Error.
Keep permission callbacks read-only and idempotent. Core may call them again\nwhile generating the Allow header.
Treat authentication and authorization separately. A valid REST nonce proves\nthe cookie-authenticated request; it does not grant a capability.
\nFor a public form, login, webhook, or callback route, verify the complete abuse\npolicy: bounded input, rate/resource limits, signature or token rules where\napplicable, replay handling, and non-enumerating responses.
\nAn analytics beacon can be intentionally public and still expose an IDOR or\ndenial-of-service primitive. Review the complete per-request work budget, not\nonly permission_callback.
maxLength, numeric\nbounds, maxItems, accepted keys, and a custom depth/node budget when core's\nschema cannot express it. A 1–2 MiB JSON cap is usually far too generous for\na beacon that should contain a few metrics.WHERE id = ? AND session_id = ?.400, 413, 422, and 429 errors. Malformed JSON or\na scalar root must not fall through into PHP warnings/5xx responses.Test cross-session record updates, replayed tokens, maximum and maximum+1 array\nsizes, oversized/deep bodies, concurrent first beacons, and repeated requests\nwith outbound integrations enabled. Assert a documented upper bound on local\nqueries/writes and zero synchronous third-party calls on the public hot path.
\nDeclare every accepted URL, query, and body parameter in args. Undeclared\nparameters are not stripped and remain readable from the request, so never pass\nget_params() or an arbitrary JSON object directly into a model/update API.
'args' => array(\n 'email' => array(\n 'required' => true,\n 'type' => 'string',\n 'format' => 'email',\n 'validate_callback' => 'rest_validate_request_arg',\n 'sanitize_callback' => 'sanitize_email',\n ),\n 'role' => array(\n 'type' => 'string',\n 'enum' => array( 'subscriber', 'contributor', 'author' ),\n 'default' => 'subscriber',\n ),\n 'count' => array(\n 'type' => 'integer',\n 'minimum' => 1,\n 'maximum' => 100,\n ),\n),\nWhen type exists and no custom sanitize_callback is set, core defaults to\nrest_parse_request_arg(), which validates the registered schema and sanitizes\nthe value. A custom sanitizer replaces that fallback. Pair it with\nvalidate_callback => rest_validate_request_arg or a custom validator, or\nconstraints such as minimum, maximum, enum, and format may not run.
Validation proves shape; sanitization normalizes data. Neither replaces\n$wpdb->prepare(), capability checks, output policy, or business validation.
Use source-specific accessors for identifiers and security decisions:
\n$request->get_url_params()$request->get_query_params()$request->get_json_params()$request->get_body_params()$request->get_file_params()get_param() and array access merge sources in this priority: JSON, form body,\nquery string, URL, defaults. Never authorize one source and mutate another.
Return supported data or WP_REST_Response on success and WP_Error on\nexpected failure. Prefer explicit response objects when setting status, headers,\nor links.
return rest_ensure_response( $data );\nreturn new WP_REST_Response( $data, 201, array( 'Location' => $location ) );\nreturn new WP_Error( 'myplugin_invalid', '...', array( 'status' => 422 ) );\nDo not call wp_send_json_*() in REST callbacks; it terminates execution and\nbypasses normal REST response handling. Do not expose exception messages,\nstack traces, SQL, paths, secrets, or internal class names in 5xx responses.
Do not expose unreviewed database rows, model objects, or metadata blobs.\nAllowlist response fields and evaluate personal/sensitive data per route and\ncontext. An email address is not safe merely because it was intentionally\nselected. Escape values when a client renders them into HTML; do not HTML-escape\nordinary JSON data indiscriminately on the server.
\nCookie-authenticated browser requests need _wpnonce or X-WP-Nonce generated\nfor wp_rest. Without a nonce, core treats cookie auth as anonymous; an invalid\nnonce returns rest_cookie_invalid_nonce with 403.
When WordPress enqueues its registered wp-api-fetch script, core installs the\nREST nonce middleware automatically, including on the front end. A decoupled\nbundle importing @wordpress/api-fetch from npm must configure nonce middleware\nitself or use another authentication scheme. Application Passwords authenticate\nexternal HTTPS requests but still require endpoint authorization; never ship\napplication credentials in public browser code.
For several related collection/item routes, extend WP_REST_Controller instead\nof duplicating registration, permission, schema, and response methods. Core\nprovides parameter helpers, not the actual query/filter/pagination behavior.\nSee reference.md.
Use a unique versioned namespace such as myplugin/v1; add v2 instead of\nbreaking an existing public contract in place.
__return_true as a vulnerability without proving the route\nshould be private or the public operation lacks necessary abuse controls.permission_callback exploitable until tracing global\nfilters and callback-internal checks; still report the fail-open registration\npattern because tooling cannot enforce the intended policy.401 versus 403 inconsistency: core normally returns 401 for\nunauthenticated denial and 403 for an authenticated but unauthorized user.wp-security-audit for the surrounding nonce, capability, input, SQL,\nfilesystem, redirect, and output checks.wp-client-side-media-processing for WordPress 7.1 media endpoints whose\nbrowser and server paths use different multi-request lifecycles.wp-abilities-api when the desired contract is a discoverable typed\noperation rather than an HTTP resource.Do not design custom JWT/OAuth/signature protocols, complete CORS/WAF/proxy\npolicy, distributed rate limiting, or OpenAPI generation here. Do not audit\ncore-owned wp/v2 contracts unless plugin code changes them.
wp-includes/rest-api.phpwp-includes/rest-api/class-wp-rest-server.phpwp-includes/rest-api/class-wp-rest-request.phpwp-includes/rest-api/endpoints/class-wp-rest-controller.phpwp-includes/script-loader.phpwp-includes/capabilities.php