Architecting Custom WordPress REST API Endpoints for Headless Integrations

The Problem: Default Endpoint Bloat

When using WordPress as a headless CMS, relying on the default /wp-json/wp/v2/ endpoints often results in "over-fetching." The standard API returns massive JSON objects containing metadata, internal IDs, and fields that the frontend application does not need. This increases payload size, slows down page loads, and exposes internal site structures to the public.

The solution is to build targeted custom endpoints that return only the specific data required by the client, reducing database load and tightening the security boundary.

Minimum Viable Design

The smallest suitable design for a custom endpoint requires three components: a unique namespace, a route pattern, and a callback function. This is implemented using the register_rest_route() function, typically hooked into rest_api_init.

Implementation Example

To expose a specific set of "Project" data (assuming a custom post type), add the following to a custom plugin or the theme's functions.php file:

add_action( 'rest_api_init', function () {
    register_rest_route( 'my-app/v1', '/projects/(?P<id>\d+)', array(
        'methods'  => 'GET',
        'callback' => 'get_project_data',
        'permission_callback' => '__return_true', // Publicly accessible
    ) );
} );

function get_project_data( $data ) {
    $post_id = $data['id'];
    $post = get_post( $post_id );

    if ( ! $post || $post->post_type !== 'project' ) {
        return new WP_Error( 'rest_not_found', 'Project not found', array( 'status' => 404 ) );
    }

    // Return only the necessary fields
    return new WP_REST_Response( array(
        'title' => $post->post_title,
        'summary' => get_post_meta( $post_id, '_project_summary', true ),
        'client' => get_post_meta( $post_id, '_project_client', true ),
    ), 200 );
}

Trust and Data Boundaries

WordPress REST API endpoints are public by default unless a permission_callback is defined. This creates a significant security risk if you are exposing internal metadata or allowing write access.

• Public Read: Use 'permission_callback' => '__return_true' only for data intended for the general public.
• Authenticated Access: For endpoints that modify data or show private info, use a callback that checks current_user_can( 'edit_posts' ).
• Input Validation: Never pass $data parameters directly into database queries. Use absint() for IDs or sanitize_text_field() for strings to prevent injection attacks.

Operational Checks and Verification

To verify the endpoint is functioning and secure, run these checks from a terminal using cURL. Replace example.com with your actual domain.

1. Verify Route Existence

Run this command to see if your namespace my-app/v1 appears in the API index:

curl -X GET https://example.com/wp-json/

2. Test Data Retrieval

Request a specific ID to ensure the callback is returning the filtered JSON object rather than the full WordPress post object:

curl -X GET https://example.com/wp-json/my-app/v1/projects/123

3. Validate Permission Boundaries

If an endpoint is intended to be private, attempt to access it without an authentication header. The expected result is a 403 Forbidden response.

Failure Modes

When to Change the Design

The simple register_rest_route approach is sufficient for low-to-medium traffic sites. However, you should shift your architecture under the following conditions:

• High-Frequency Polling: If the frontend requests this data every few seconds, the database overhead will crash the site. Introduce a caching layer (like Redis) or a persistent object cache to store the WP_REST_Response.
• Complex Filtering: If you need advanced searching, sorting, and pagination, stop writing custom callbacks and instead extend the WP_REST_Posts_Controller class to leverage built-in WordPress query logic.
• Large Data Sets: If you are returning hundreds of items, implement pagination by utilizing the X-WP-Total and X-WP-TotalPages headers.