Handling Featured Images in Headless WordPress via REST API

The Missing Image ID Problem

When building a decoupled frontend (like React or Next.js) using the WordPress REST API, you will notice a frustrating gap: the default /wp-json/wp/v2/posts endpoint provides a featured_media field, but it only returns an integer ID. To actually display the image, your frontend must make a second, separate network request to the media endpoint to fetch the image URL, which slows down page loads and increases API overhead.

The most efficient solution is to modify the REST API response on the server side to include the full media object—including the source URL and alt text—directly within the post object.

Enabling Post Thumbnails

Before the API can serve image data, the WordPress theme must explicitly support featured images. This is handled in the functions.php file of your active theme. Without this declaration, the "Featured Image" meta box will not appear in the admin dashboard, and the featured_media field will remain empty.

// Add this to your theme's functions.php
add_theme_support( 'post-thumbnails' );

Injecting Media Data into the REST Response

To avoid the "N+1 query problem" (where you fetch one post and then N images), use register_rest_field. This allows you to create a custom field in the API response that performs the lookup on the server before the JSON is sent to the client.

Below is the implementation to add a featured_image_src field to the posts endpoint. This code should be placed in functions.php or a custom site plugin.

add_action( 'rest_api_init', 'add_featured_image_to_rest_api' );

function add_featured_image_to_rest_api() {
    register_rest_field( 'post', 'featured_image_src', array(
        'get_callback' => function( $post_array ) {
            // Get the ID of the featured image
            $thumbnail_id = get_post_thumbnail_id( $post_array['id'] );
            
            if ( $thumbnail_id ) {
                // Return the full URL of the 'full' size image
                return wp_get_attachment_image_src( $thumbnail_id, 'full' )[0];
            }
            
            return null;
        },
        'update_callback' => null,
        'schema'          => array(
            'description' => 'The URL of the featured image',
            'type'        => 'string',
        ),
    ) );
}

Execution and Permissions

• Where to run: Add this code to the functions.php file of a child theme or a custom plugin.
• Permissions: Requires filesystem access to the WordPress installation or a plugin editor.
• Expected Result: When calling /wp-json/wp/v2/posts, each post object will now contain a featured_image_src key with a direct URL string.

Trade-offs and Limitations

While this approach reduces the number of HTTP requests, it introduces a slight increase in server-side processing time per request. If you are requesting 100 posts at once, WordPress must perform 100 additional metadata lookups before sending the response.

Additionally, this implementation only returns the 'full' size image. If your frontend requires multiple sizes (thumbnail, medium, large) for responsive images, you should modify the get_callback to return an associative array of all available sizes instead of a single string.

Verification Steps

To verify the implementation without a frontend, use a curl command or a browser to hit the API endpoint for a specific post that has a featured image assigned:

curl -X GET https://your-site.com/wp-json/wp/v2/posts/1

Search the JSON output for the featured_image_src key. If it returns a valid URL, the integration is successful. If it returns null, verify that the post actually has a featured image assigned in the WordPress admin panel.