WordPress as a Headless CMS: REST vs GraphQL in 2026

I’ve built headless WordPress sites with both the REST API and WPGraphQL. After living with both in production, I have opinions — and they might not match the conventional wisdom.

The REST API: What You Get Out of the Box

WordPress ships with a full REST API. No plugins, no setup. Every post type, taxonomy, and media item has endpoints.

const res = await fetch(
  'https://wp.example.com/wp-json/wp/v2/posts?per_page=10&_embed'
);
const posts = await res.json();

The _embed parameter inlines related data like featured images and author info. Without it, you’re making N+1 requests.

Strengths: Zero setup, automatic endpoints for any registered post type, straightforward authentication, and CDN-friendly HTTP caching.

Weaknesses: Over-fetching (30+ fields per post whether you need them or not), under-fetching (related data requires multiple requests or custom endpoints), and response shapes dictated by WordPress.

WPGraphQL: Query What You Need

WPGraphQL adds a GraphQL endpoint. You specify exactly what data you want:

const query = `
  query GetPosts {
    posts(first: 10) {
      nodes {
        title
        slug
        excerpt
        date
        featuredImage {
          node {
            sourceUrl
            altText
          }
        }
        categories {
          nodes {
            name
            slug
          }
        }
      }
    }
  }
`;

One request. Exactly the fields you need. Posts, images, and categories in one response.

Strengths: No over-fetching, single request for complex nested data, self-documenting typed schema, and TypeScript code generation support.

Weaknesses: Requires a plugin, inconsistent plugin compatibility, POST-based requests break CDN caching, and a learning curve for GraphQL newcomers.

Performance in Practice

REST with _embed sends more data but caches beautifully at the CDN level. GraphQL sends less data but POST requests aren’t cached by default — you need WPGraphQL Smart Cache or a server-side caching layer.

For Next.js with ISR, both are roughly equivalent. The page is statically generated regardless. The API call only happens during revalidation. But for client-side fetching, the caching story matters significantly.

Developer Experience

GraphQL is better for frontend developers — typed schema, code generation, precise data fetching. REST is better for WordPress developers — no plugin to maintain, every tutorial uses it, and custom endpoints are straightforward:

add_action('rest_api_init', function () {
    register_rest_route('custom/v1', '/featured-content', [
        'methods'  => 'GET',
        'callback' => function () {
            return [
                'hero_post' => get_hero_post(),
                'recent'    => get_recent_posts(5),
                'featured'  => get_featured_projects(3),
            ];
        },
        'permission_callback' => '__return_true',
    ]);
});

Custom REST endpoints solve the under-fetching problem. Shape the response to match your frontend’s needs — most of GraphQL’s benefit without the dependency.

Plugin Ecosystem in 2026

WPGraphQL has matured. ACF, Gravity Forms, Yoast SEO, and most major plugins now have GraphQL extensions. But niche plugins might require writing your own resolvers. REST compatibility is universal — if a plugin registers a post type correctly, it’s available via REST automatically.

My Recommendation

Choose REST if: Small team, straightforward data needs, zero additional plugins, or ISR/SSG where caching is handled by your frontend framework.

Choose GraphQL if: Complex data relationships, frontend team comfortable with GraphQL, performance-critical client-side rendering, or you want typed code generation.

I use REST with custom endpoints. Data shapes are tailored to my pages, caching works out of the box, and there’s no extra plugin to maintain. The honest truth: for most headless WordPress projects, the choice matters less than getting your caching strategy right.