Two GraphQL Servers, One CMS

WordPress now has two mature GraphQL server plugins: WPGraphQL and GraphQL API for WordPress. Both do the same fundamental job — exposing WordPress data through a GraphQL API — but they take different architectural approaches. Those differences matter for specific use cases.

WPGraphQL has been around longer and reached version 1.0 recently. GraphQL API for WordPress is newer and was built by the author of this article. A fair assessment of the two requires looking at concrete scenarios rather than feature lists, because each plugin has strengths that make particular tasks noticeably easier.

When WPGraphQL Is The Clear Choice

For several common headless setups, there is no real decision to make — WPGraphQL is the only option that works out of the box.

Gatsby And Next.js Projects

If you are building with Gatsby, WPGraphQL is the only choice. The Gatsby source plugin for WordPress is built exclusively for WPGraphQL. Gatsby pulls all the data it needs from WordPress at build time, then takes over the application logic entirely. Once that data transfer happens, additional GraphQL server features don't matter much — WPGraphQL is already fully sufficient for Gatsby's needs.

The same reasoning applies to several new Next.js-based starter projects that have appeared in the headless WordPress space:

All three are built on WPGraphQL. They would need to operate with GraphQL through an abstraction layer to support swapping in a different server, and currently none of them does. There has been some discussion about adding such an interface, but nothing concrete has materialized.

Static Site Generation Generally

Beyond these specific frameworks, WPGraphQL is the right tool for any static site builder. A static site generator fetches data from WordPress once and then stops depending on it. Since WPGraphQL has completely mapped the GraphQL schema — a task still in progress for GraphQL API for WordPress — and provides everything a generator needs, it remains the most suitable option for this use case.

Frontity: Either Server Works

Frontity takes a different approach than Gatsby or the Next.js starters. It manages application state without exposing how data was obtained, and it relies on a source plugin as an interface between the framework and the data provider. The default source plugin uses the WordPress REST API, but anyone can implement a source plugin for either GraphQL server.

This architecture means neither WPGraphQL nor GraphQL API for WordPress has an inherent advantage for Frontity projects. Both require initial setup effort, and neither is integrated out of the box.

When GraphQL API For WordPress Makes Sense

The calculus changes when WordPress is serving a live website rather than feeding a static build. If you are powering a mobile app, displaying real-time data, or mixing static and dynamic content, the GraphQL server itself becomes part of the user-facing stack. That raises two concerns: security and speed.

Consider a static blog with user comments. Rendering comments statically means triggering a rebuild whenever someone posts — which can take minutes and burn server time if comments are frequent. An alternative is to render the page without comments and fetch them client-side from a live API. That is where the GraphQL server’s characteristics matter.

Security And Caching

WPGraphQL does implement security measures like disabling introspection by default. GraphQL API for WordPress goes further by disabling its single endpoint by default, relying instead on natively supported persisted queries. Those persisted queries also improve performance, because responses can be cached via HTTP caching across client, CDN, and server layers.

Different Schemas For Different Audiences

WordPress often serves content to multiple applications and user types — paid versus free users, mobile app versus website. That calls for different versions of the GraphQL schema.

WPGraphQL allows schema modifications through code, but the process is awkward. Schema variations are not easy to map to specific audiences, and all queries still flow through the single /graphql endpoint.

GraphQL API for WordPress supports custom endpoints natively, such as:

  • /graphql/mobile-app and /graphql/website
  • /graphql/pro-users and /graphql/regular-users

Each endpoint can be configured through access control lists for field-level granularity, with a public or private API mode controlling schema metadata visibility. These configurations integrate with the WordPress editor, meaning custom GraphQL schemas can be built visually rather than requiring custom code.

For scenarios where WordPress must expose different data to different consumers or handle requests in real time, GraphQL API for WordPress offers a more natural fit.

GraphQL as an Integration Tool

Beyond simple data fetching, GraphQL can process and modify data by handing it off to external services — for example, sending text to a third-party API for grammar correction or uploading media to a CDN. The cleanest way to accomplish this is through directives, which act like WordPress filters during data creation or retrieval.

WPGraphQL does not document how to interact with external services, and its codebase offers no directive examples. GraphQL API for WordPress, in contrast, supports directives natively. Each directive in a query executes once in total, rather than once per field, which makes external API calls highly efficient. A query using a @translate directive, for instance, can send all titles and excerpts of many posts to the Google Translate API in a single call, translating them from English to Spanish together. GraphQL API for WordPress is a natural fit for this kind of service orchestration.

Community and Ecosystem

WPGraphQL has built a strong support community around it. If you need help troubleshooting, you will likely find someone familiar with the plugin. GraphQL API for WordPress does not yet have a comparable user base.

In terms of feature adoption, GraphQL API for WordPress positions itself as a forward-looking server. It regularly implements proposals from the GraphQL specification ahead of time, offering opt-in features like multiple query execution and schema namespacing. WPGraphQL is more conservative in this regard.

Where WPGraphQL clearly leads is in schema coverage. It maps the entire WordPress data model, including posts, custom post types, taxonomies, media, menus, settings, users, comments, plugins, themes, and widgets. GraphQL API for WordPress covers most of these but currently lacks plugins, themes, and widgets. If you need data from those sources, only WPGraphQL can do the job today.

The extension ecosystems also differ. WPGraphQL has extensions for popular plugins such as Advanced Custom Fields, WooCommerce, Yoast, and Gravity Forms. GraphQL API for WordPress offers an extension for Events Manager, with more planned after version 1.0.

Gutenberg and Distributed Blocks

Both plugins are working on GraphQL integration with Gutenberg, but they take different paths. WPGraphQL has proposed three approaches, all of which require a server-side registry in WordPress core to identify blocks in the GraphQL schema. This makes its solution tentative, as it depends on community acceptance of that registry.

GraphQL API for WordPress uses a “create once, publish everywhere” strategy. It extracts block data from stored content and represents all blocks with a single Block type, which could avoid the need for a server-side registry entirely. Because the solution depends only on the plugin itself and is already in progress, it has a higher chance of shipping soon.

There is a broader problem: few plugins use GraphQL to power their own functionality, including Gutenberg blocks. Neither WPGraphQL nor GraphQL API for WordPress is part of WordPress core, so plugins cannot rely on either the way they rely on the REST API. Waiting for GraphQL to enter core could take years, and core changes like bumping the minimum PHP version to 7.1 are prerequisites.

A potential short-term solution comes from scoping. The author of GraphQL API for WordPress has solved PHP scoping for the plugin, which opens the door to distributing a smaller, self-contained Private GraphQL API as a Composer dependency. Plugins could embed this private engine to power their own blocks without conflicting with other code or with other embedded copies. This works regardless of whether the full GraphQL API for WordPress plugin is also installed, and it is currently under development, with an expected release in a few weeks.

Which to Choose

The two plugins serve different strategies. WPGraphQL is the safe, community-backed option with complete schema coverage. GraphQL API for WordPress offers advanced data manipulation, innovative features, and the Private GraphQL API for plugin distribution, albeit with a smaller community. In broad terms: choose WPGraphQL for static or conventional use, and GraphQL API for WordPress when you need live data processing or plan to embed GraphQL in a plugin.

Finally, the ecosystem would benefit if headless frameworks such as Next.js adopted the Frontity approach — accessing an interface to fetch data rather than wiring directly to one implementation. That would let developers select the underlying GraphQL server per project based on their needs.

Resources