Choosing how your headless front end talks to WordPress is one of the first architectural decisions you make on a decoupled build — and it shapes performance, caching, and developer velocity for the life of the project. The two realistic options are the built-in WordPress REST API and the WPGraphQL plugin. This guide compares them on the axes that actually matter to developers and agencies, then gives clear decision guidance.
What is the WordPress REST API?
The WordPress REST API is a resource-based interface built into WordPress core that exposes posts, pages, users, taxonomies, and custom post types as JSON over standard HTTP endpoints. No plugin is required — every WordPress site ships with it at /wp-json/wp/v2/.
Each resource lives at its own URL. You fetch a post from /wp-json/wp/v2/posts/123, its comments from /wp-json/wp/v2/comments?post=123, and its media separately again. Because each endpoint is a unique, cacheable URL, the REST API plays beautifully with HTTP and CDN caching. The tradeoff: you take whatever fields the endpoint returns, and related data usually means more round-trips.
What is WPGraphQL?
WPGraphQL is an open-source plugin that adds a single GraphQL endpoint to WordPress, letting clients request exactly the fields they need — across multiple resource types — in one strongly typed query. It is the de facto standard for serious headless WordPress stacks built on React and Next.js.
Instead of many URLs, WPGraphQL exposes one endpoint at /graphql. You send a query describing the shape of the data you want — a post, its author, its featured image, and its categories — and you get back precisely that, nothing more. The schema is introspectable, so tools like GraphiQL can auto-document every available field. If you are planning a decoupled stack, our guide to headless WordPress with React and Next.js shows where WPGraphQL fits in the wider architecture.
Over-fetching, under-fetching, and request count
REST tends to over-fetch (returning fields you do not need) and under-fetch (forcing extra requests for related data), while WPGraphQL returns exactly the requested fields in a single round-trip. This is the single biggest technical difference between the two.
A REST call to /posts returns content, excerpt, all taxonomies, and metadata even if your component only needs a title and slug — then you make a second call for the author and a third for the featured image. WPGraphQL solves the N+1 problem internally with a DataLoader pattern that batches related lookups, so one query can resolve posts, authors, and images together. WPGraphQL’s own benchmark documentation reports fetching 100 posts at roughly 6.4 KB versus 335 KB over REST for the equivalent data — a meaningful payload difference on mobile networks where Largest Contentful Paint is sensitive to transfer size.
Caching: where REST quietly wins
REST’s unique, query-string-addressable URLs make edge and CDN caching trivial; WPGraphQL’s single POST endpoint needs a dedicated caching layer to match that simplicity. This is the gap most comparison articles skip.
Most GraphQL requests are HTTP POSTs to one URL, and POSTs are not cached by default by CDNs or browsers. To get REST-like edge performance, WPGraphQL teams add object caching, persisted queries, or the WPGraphQL Smart Cache plugin, which tags and invalidates query results. REST gets HTTP caching essentially for free. If raw CDN cacheability and zero extra moving parts are priorities, that is a genuine point in REST’s favour — and it interacts directly with the rest of your technical SEO setup for WordPress.
Schema, typing, and developer experience
WPGraphQL enforces a strongly typed, self-documenting schema; the REST API supports schema registration but does not enforce it, so plugin-registered fields are often inconsistent.
In GraphQL every field declares its return type, which enables introspection, autocomplete, and compile-time safety with TypeScript code generation. With REST, custom fields registered by plugins like Advanced Custom Fields can return a null, an object, or an array of objects depending on configuration — a frequent source of front-end bugs. For teams shipping typed React or Next.js front ends, that predictability shortens debugging cycles considerably. This is also a factor in the broader React vs WordPress decision.
Side-by-side comparison
Use the table below as a quick reference; the right choice depends on query complexity, caching strategy, and team familiarity more than on raw speed alone.
| Factor | WordPress REST API | WPGraphQL |
|---|---|---|
| Installation | Built into core, zero setup | Plugin install + config |
| Endpoints | Many resource URLs | One /graphql endpoint |
| Over/under-fetching | Common; extra round-trips | Request exact fields, one query |
| Schema/typing | Supported, not enforced | Strongly typed, introspectable |
| CDN/edge caching | Native via unique URLs | Needs Smart Cache / persisted queries |
| Query-cost abuse risk | Low (fixed responses) | Needs depth/complexity limits |
| Best for | Simple reads, prototypes, CDN-heavy sites | Complex, relational, fully decoupled apps |
Security and query-cost considerations
REST responses are fixed and predictable, while WPGraphQL’s flexibility means a single malicious deeply nested query can be expensive — so production WPGraphQL needs query depth and complexity limits.
Because clients control the shape of a GraphQL query, an unbounded request can ask for posts → comments → authors → posts in a costly loop. Mitigations include query depth limiting, complexity scoring, and persisted (allow-listed) queries that reject anything not pre-approved. REST sidesteps this class of issue because each endpoint returns a bounded, server-defined payload. Both APIs share WordPress’s standard authentication (application passwords, JWT, OAuth), so auth complexity is broadly comparable.
Which should you use for headless WordPress?
Choose WPGraphQL for complex, relational, app-like front ends where precise data fetching and type safety pay off; choose the REST API for simpler builds, rapid prototypes, or sites that lean heavily on CDN edge caching.
- Pick WPGraphQL when: you are building a Next.js or React app with nested data, want TypeScript code generation, or are integrating headless WooCommerce where product, variation, and cart data are deeply relational.
- Pick the REST API when: requirements are simple, you want zero plugin dependencies, your team already knows REST, or your performance strategy is built around aggressive CDN caching of unique URLs.
- Consider both: nothing stops you from using REST for cacheable public reads and WPGraphQL for complex authenticated views in the same project.
For most modern decoupled projects we ship, WPGraphQL is the default because the developer experience and single-request efficiency outweigh the added caching work — but the REST API remains the pragmatic, dependency-free choice for lighter builds. To understand the wider stack these APIs plug into, see what a headless CMS is.
Planning a headless WordPress build and not sure which API fits your data model, caching, and team? Our engineers architect decoupled WordPress, React, and Next.js stacks every week. Explore our custom WordPress development services to scope the right approach for your project.
Frequently asked questions
For complex, relational data WPGraphQL is usually faster because it returns exactly the requested fields in one batched request instead of several over-fetching REST calls. WPGraphQL’s own benchmarks show large payload reductions for the same data. For simple single-resource reads served from a CDN, however, cached REST endpoints can be just as fast.
Yes. WordPress core does not include GraphQL, so you install the open-source WPGraphQL plugin to add a single /graphql endpoint. The REST API, by contrast, is built into WordPress core and available at /wp-json with no plugin required, which is part of why REST is often chosen for lightweight builds.
The REST API exposes each resource as a unique URL, so CDNs and browsers cache responses natively. WPGraphQL typically uses one POST endpoint, and POST requests are not cached by default. To match REST-like edge performance you add object caching, persisted queries, or the WPGraphQL Smart Cache plugin to tag and invalidate results.
Yes, and many production headless builds do. You can serve cacheable public reads through REST’s unique URLs while handling complex, relational, or authenticated views through WPGraphQL. Running both adds some maintenance overhead, but it lets each API do what it does best without forcing a single compromise across the whole project.
WPGraphQL is production-ready, but because clients control query shape you must add query depth limits, complexity scoring, and ideally persisted (allow-listed) queries to prevent expensive nested requests. Both APIs share WordPress’s standard authentication options like application passwords and JWT, so authentication complexity is broadly similar between them.
