When Headless WordPress Makes Sense: REST API + Next.js Integration

When headless WordPress is justified?

You already have a site on WordPress, but clients complain about slow loading, and editors are used to the admin panel. Migrating to another CMS risks losing content and SEO positions. Headless WordPress keeps the admin for content while the frontend is rewritten on a modern stack (Next.js, React, Vue). This gives SPA speed, component flexibility, and a familiar editor. Do not choose headless if the site is built from scratch and there are no strict requirements — regular WordPress is simpler and cheaper.

How we do it: a real case study

For one project, we used WordPress + Next.js 14 with ISR. Initial data: 10,000 posts, 5 categories, ACF fields for portfolio. Problem: pages loaded in 4 seconds (LCP > 4s). After headless integration, LCP dropped to 1.2s, TTFB from 800 to 120ms. Server load reduced by 3x (from 8 to 3 requests per page).

Key steps:

• REST API setup — enabled _fields to minimize response, disabled unused endpoints.
• CORS and security — allowed only the frontend domain, added Origin validation.
• ACF in API — via register_rest_field added meta fields directly to the response.
• Next.js API client — single fetch with ISR revalidate.
• Webhook on-demand revalidation — when a post is published, WordPress sends a POST to /api/revalidate in Next.js.

Result: page load speed increased by 70%, SEO traffic grew by 25% in one month.

Technical implementation: from REST API to on-demand revalidation

WP REST API: base endpoints and optimization

WordPress REST API is built-in since version 4.7. Base URL: https://site.com/wp-json/wp/v2/. It is critical to use the _fields parameter — by default the response contains dozens of fields, most unnecessary.

# List posts with required fields GET /wp-json/wp/v2/posts?_fields=id,title,slug,date,excerpt,featured_media&per_page=10 

How to configure CORS for headless WordPress?

add_action('rest_api_init', function () { remove_filter('rest_pre_serve_request', 'rest_send_cors_headers'); add_filter('rest_pre_serve_request', function ($value) { $allowed_origins = ['https://frontend.site.com', 'http://localhost:3000']; $origin = $_SERVER['HTTP_ORIGIN'] ?? ''; if (in_array($origin, $allowed_origins, true)) { header("Access-Control-Allow-Origin: {$origin}"); header('Access-Control-Allow-Methods: GET, POST, OPTIONS'); header('Access-Control-Allow-Headers: Authorization, Content-Type'); } return $value; }); }, 15); 

Extending the REST API: ACF and custom endpoints

add_action('rest_api_init', function () { register_rest_field('portfolio', 'acf', [ 'get_callback' => function ($post) { return get_fields($post['id']); }, 'schema' => ['type' => 'object'], ]); register_rest_route('app/v1', '/home', [ 'methods' => 'GET', 'callback' => function (WP_REST_Request $request) { return rest_ensure_response([ 'hero' => get_fields(get_option('home_hero_page_id')), 'featured' => array_map(fn($p) => [ 'id' => $p->ID, 'title' => get_the_title($p), 'slug' => $p->post_name ], get_posts(['post_type' => 'portfolio', 'posts_per_page' => 3])), ]); }, 'permission_callback' => '__return_true', ]); }); 

Integration with Next.js: ISR and preview mode

const WP_API = process.env.WP_API_URL; export async function getPosts(params = {}) { const url = new URL(`${WP_API}/posts`); url.searchParams.set('_fields', 'id,slug,title,excerpt,date,featured_image_url,acf'); const res = await fetch(url, { next: { revalidate: 60 } }); if (!res.ok) throw new Error(`WP API error: ${res.status}`); return { posts: await res.json(), total: Number(res.headers.get('X-WP-Total')) }; } 

For preview mode, add an API route /api/preview that activates draftMode and redirects to the target post.

On-demand revalidation: WordPress → Next.js

When a post is saved, WordPress sends a POST to /api/revalidate:

export async function POST(req: Request) { const { secret, slug } = await req.json(); if (secret !== process.env.REVALIDATE_SECRET) return Response.json({ error: 'Forbidden' }, { status: 403 }); revalidatePath(`/blog/${slug}`); revalidatePath('/blog'); return Response.json({ revalidated: true }); } 

Caching and performance

REST API is not cached by default. We add Redis Object Cache or Nginx cache for anonymous requests. This reduces TTFB by 30–50% and database load by 2x. If you have high speed requirements, we use Edge Cache (Cloudflare) with purge via webhook.

What's included and timelines

• Headless setup (CORS, ACF, endpoints) — 6–8 hours.
• Next.js integration (client, ISR, preview) — 1–1.5 business days.
• Webhook and on-demand revalidation — 3–4 hours.

We provide a 3-month warranty on the code and free support after deployment. With 10+ years of experience, we have integrated WordPress with dozens of projects — from landing pages to portals with millions of visitors. Contact us — we will evaluate your project in one day.

Comparison: Headless vs Traditional WordPress

Headless WordPress is a reasonable choice when performance and frontend control are important. Not suitable if the budget is limited or you lack frontend developers. Get a consultation: we will help you choose the architecture and evaluate your project free of charge. Order integration — first results in 2 days.

Additional resources: REST API and ISR.