When we talk about extending WordPress beyond its core content management capabilities, the built-in REST API is an invaluable tool. While the default endpoints for posts, pages, and custom post types are incredibly flexible, there are often scenarios where we need to expose highly specific data or actions that don’t fit neatly into the existing structure. This is where crafting our own custom REST endpoints comes into play, giving us granular control over data exposure, request validation, and, most importantly, robust authentication mechanisms.
Let’s consider a practical scenario: imagine we’ve developed a custom plugin that manages ProductReview custom post types for an e-commerce site. Our objective is to allow a dedicated, external review submission application to create new product reviews directly, but with specific submission logic and strict security. The default /wp/v2/product-review endpoint might work, but we want a specialized endpoint that handles specific input validation, sets a pending status by default, and demands a specific form of authentication for this single purpose.
Our first step is to register this custom route using register_rest_route. This function typically lives within our plugin’s main file or an included setup file, hooked into rest_api_init. We define a unique namespace to prevent conflicts, then the route itself, and an array of arguments that dictate HTTP methods, the callback function to handle the request, and a crucial permission callback for authorization.
Here’s how we might structure the registration for our /submit-review endpoint:
add_action( 'rest_api_init', function () {
register_rest_route( 'my-reviews/v1', '/submit-review', [
'methods' => 'POST',
'callback' => 'my_plugin_submit_product_review',
'permission_callback' => 'my_plugin_can_submit_review',
'args' => [
'product_id' => [
'sanitize_callback' => 'absint',
'required' => true,
'validate_callback' => function( $param, $request, $key ) {
// Ensure product_id exists and refers to a 'product' post type.
return is_numeric( $param ) && get_post_type( $param ) === 'product';
}
],
'reviewer_name' => [
'sanitize_callback' => 'sanitize_text_field',
'required' => true,
],
'review_content' => [
'sanitize_callback' => 'sanitize_textarea_field',
'required' => true,
],
'rating' => [
'sanitize_callback' => 'absint',
'required' => true,
'validate_callback' => function( $param, $request, $key ) {
// Validate rating is between 1 and 5.
return $param >= 1 && $param <= 5;
}
],
],
] );
} );In this snippet, we’ve defined a POST endpoint under the my-reviews/v1 namespace. Notice the args array: this is vital for defining expected parameters, applying WordPress’s robust sanitization functions, and including custom validation logic. This preemptive data integrity check is a critical security layer right at the API gateway.
Next, we implement the callback function, my_plugin_submit_product_review. This function receives the WP_REST_Request object, allowing us to safely access all request parameters after they’ve passed our defined sanitization and validation. Inside, we handle the actual logic for creating our ProductReview custom post type.
function my_plugin_submit_product_review( WP_REST_Request $request ) {
$product_id = $request->get_param( 'product_id' );
$reviewer_name = $request->get_param( 'reviewer_name' );
$review_content = $request->get_param( 'review_content' );
$rating = $request->get_param( 'rating' );
$post_id = wp_insert_post( [
'post_title' => sanitize_text_field( "Review for Product {$product_id} by {$reviewer_name}" ),
'post_content' => wp_kses_post( $review_content ), // Ensure HTML is properly escaped/filtered
'post_status' => 'pending', // All new reviews start as pending moderation
'post_type' => 'product_review',
'meta_input' => [
'product_id' => $product_id,
'reviewer_name' => $reviewer_name,
'rating' => $rating,
],
], true ); // The second parameter ensures WP_Error is returned on failure
if ( is_wp_error( $post_id ) ) {
return new WP_REST_Response( [ 'success' => false, 'message' => $post_id->get_error_message() ], 500 );
}
return new WP_REST_Response( [ 'success' => true, 'review_id' => $post_id ], 201 );
}Crucially, securing this endpoint requires a permission_callback. For third-party applications or services, WordPress Application Passwords are an excellent authentication method. They allow us to generate unique, revocable passwords for specific users, granting API access without exposing their primary WordPress password. Our my_plugin_can_submit_review function would check if the request is authenticated and if the user associated with the application password possesses the necessary capabilities.
function my_plugin_can_submit_review( WP_REST_Request $request ) {
// This checks if the user authenticated via Application Password
// has the 'edit_product_reviews' capability (which we'd custom assign).
return current_user_can( 'edit_product_reviews' );
}This permission callback ensures that only authenticated requests from a user with the edit_product_reviews capability (which we’d assign to a custom role or an appropriate existing role like ‘editor’) can successfully hit our submission endpoint. The WordPress REST API automatically handles the Application Password authentication via the Authorization: Basic header, so our current_user_can check works seamlessly.
By combining register_rest_route with robust args for input validation, a well-structured callback function for business logic, and a precise permission_callback utilizing WordPress Application Passwords, we can build highly secure and specialized backend interfaces. This approach grants us fine-grained control over our API, ensuring only valid, authenticated requests can interact with our WordPress data in the exact manner we intend, paving the way for seamless, secure integration with external services and applications.
