The WordPress REST API provides powerful default endpoints for posts, pages, users, and media. But real plugin functionality often needs custom endpoints that expose your plugin’s specific data and operations. Custom endpoints let you create the exact API surface your application needs, following your data model and business logic.
This guide covers how to create custom REST API endpoints for your WordPress plugin, from basic route registration to complex query handling.
Route Registration
Register custom endpoints with register_rest_route() during the rest_api_init hook. Each route has a namespace (your plugin’s identifier with version), a route path, and an array of endpoints. Each endpoint specifies HTTP methods, a permission callback, and a handler callback. The namespace should follow the pattern ‘your-plugin/v1’.
Routes can include path variables using regex syntax within parentheses. A route like ‘/bookings/(?P
Request and Response
The handler callback receives a WP_REST_Request object containing parameters, headers, and authentication data. Use $request->get_param() to access individual parameters, $request->get_params() for all parameters, and $request->get_header() for HTTP headers. Return a WP_REST_Response or WP_Error object from your handler.
Set appropriate HTTP status codes: 200 for successful GET requests, 201 for created resources, 400 for bad requests, 403 for forbidden, and 404 for not found. Use rest_ensure_response() to normalize your response data into the standard REST API format.
Schema Registration
A schema describes your endpoint’s data structure and is used for documentation, validation, and discovery. Register a schema with register_rest_field() or include it directly in your route registration. The schema defines properties, their types, whether they’re required, and default values.
WordPress automatically validates request parameters against your schema and returns meaningful error messages when validation fails. A well-defined schema makes your API easier to use and more reliable.
Permission Callbacks
Every endpoint needs a permission callback that returns true or false. For public endpoints, return ‘__return_true’. For authenticated-only endpoints, check is_user_logged_in(). For role-specific endpoints, use current_user_can().
Be specific about permissions. A user might have permission to read their own data but not others. Check resource ownership in the permission callback by comparing the current user ID with the resource owner ID.
Collection Endpoints
Collection endpoints return lists of resources. Support pagination with the ‘per_page’ and ‘page’ parameters. Use WP_Query or get_posts() with the pagination parameters applied. Return pagination headers with $response->header(‘X-WP-Total’, $total) and $response->header(‘X-WP-TotalPages’, $pages).
Support filtering with custom query parameters like ‘search’, ‘after’, ‘before’, and plugin-specific filters. Document supported parameters clearly. If your endpoint returns many resources, ensure it’s properly indexed and performant.
Il punto fondamentale
Custom REST API endpoints transform your plugin from a WordPress-specific tool into a platform that can integrate with any application. Register routes with proper namespacing, handle requests and responses with the correct WordPress classes, define schemas for documentation and validation, and secure endpoints with proper permission callbacks. A well-designed API extends your plugin’s reach far beyond the WordPress admin.