Headless WordPress seems to be all the rage these days, with a number of new developments taking place in the past few weeks. One reason for the explosion of activity was the release of version 1.0 of WPGraphQL, a GraphQL server for WordPress.
WPGraphQL provides a GraphQL API: a way to get data from and publish data from a WordPress site. It allows us to decouple the experience of managing our content (done through WordPress) from rendering the site, for which we can use the framework library of our choice (React, Vue. Js, Gatsby, Next-js or whatever).
Until recently, WPGraphQL was the only GraphQL server for WordPress. But now there is one. The GraphQL API for WordPress was written by me.
The purpose of both plug-ins is the same: to provide the GraphQL API for WordPress sites. You might want to know. Why have another plug-in when you already have WPGraphQL? Do these two plug-ins do the same thing? Or are they for different situations?
Let me say something first. WPGraphQL is very handy. I didn’t build my plugin because there was something wrong with it.
I built the GraphQL API for WordPress because I’ve been working on an engine for retrieving data efficiently, and that engine happens to be perfect for GraphQL. So then I said to myself, “Why not?” And then I built it. There are other reasons as well).
The two plug-ins have different architectures, giving them different characteristics that make it easier to implement specific tasks through one plug-in or the other.
In this article, I will start from my own point of view, but describe as objectively as possible, when WPGraphQL is the way to go and when the GraphQL API for WordPress is a better choice.
Use WPGraphQL if. The use of Gatsby
If you’re using Gatsby to build a website, there’s only one option. WPGraphQL.
The reason is that only WPGraphQL has the Gatsby source plugin for WordPress. Additionally, Jason Bahl, the creator of WPGraphQL, was employed by Gatsby until recently, so we can be sure that this plugin will fit Gatsby’s needs.
Gatsby receives all the data from the WordPress site, and from then on, the logic of the application will be entirely on Gatsby’s side, not WordPress. Therefore, any additions to WPGraphQL, such as the @stream or @defer directives that might be added, won’t make much of a difference.
WPGraphQL is as good as Gatsby needs.
Using WPGraphQL, if. Use one of the new headless frames
As I mentioned, there has been a lot of activity in the WordPress headless space recently for several new frameworks and launch projects, all based on next.js.
- Colby Fayock created the Next. Js WordPress Starter.
- WebDevStudios has launched its own Next. Js WordPress Starter.
- WP Engine creates the Headless WordPress framework, which powers its services for hosting and deploying Headless WordPress sites.
If you need to use any of these new headless frameworks, you’ll need to use WPGraphQL because they’re all built on top of this plug-in.
That’s kind of unfortunate. I really want the GraphQL API for WordPress to power them as well. But to do this, these frameworks need to work with GraphQL through an interface so that we can swap GraphQL servers.
I kind of wish that any of these frameworks would put such an interface in place. I asked this question on the discussion board of the Headless WordPress framework and was told it might be considered. I also asked on WebDevStudios’ Next. Js WordPress Starter discussion board, but unfortunately my question was immediately deleted without any response. (That’s not encouraging, is it?)
So, for now and for the foreseeable future, this is what WPGraphQL looks like.
If one (or both) is used. Using Frontity
Frontity is a WordPress React framework. It allows you to build a React based application, managed via WordPress on the back end. Even using the WordPress editor to create blog posts is out of the box.
Frontity manages application status without compromising how data is obtained. Although it is reST-based by default, you can also power it through GraphQL by implementing the corresponding source plug-in.
This is where Frontity is smart: the source plug-in is an interface to communicate with the data provider. Currently, the only source plug-in available is for the WordPress REST API. But anyone can implement a source plug-in for WPGraphQL or WordPress’s GraphQL API. This is how I want the framework based on next.js to replicate).
Conclusion. Neither WPGraphQL nor the GraphQL API offers any advantage in working with Frontity, and both require some initial effort to insert them.
Using WPGraphQL, if. Create a static website
In the previous two sections, the conclusion was the same: use WPGraphQL. But my reaction to this conclusion is different. I had no regrets about Gatsby, and I felt compelled to do something about next.js.
Why is that?
The difference is that Gatsby was purely a static website generator, while Next. Js can power both static and real-time websites.
I mentioned that WPGraphQL is good enough for Gatsby. This statement can actually be expanded. WPGraphQL is good enough for any static web site generator. Once the static site generator gets the data from the WordPress site, it’s basically settled with WordPress.
Even if WordPress’s GraphQL API provides additional functionality, it probably won’t have any impact on the static site generator.
So, because WPGraphQL is good enough and it fully maps the GraphQL schema (which is still a work in progress for the GraphQL API for WordPress), WPGraphQL is the most appropriate choice, now and for the foreseeable future.
Use the GraphQL API if. Use GraphQL in a live (that is, non-static) website
Now, that changes if we want GraphQL to pull data from a live web site, such as powering a mobile application or drawing live data on a web site (for example, display analysis) or combining static and live methods on the same web site.
For example, let’s say we’ve built a simple static blog using one of the Next. Js frameworks, and we want users to add comments to blog posts. How should this task be handled?
We have two choices: static and real-time (or dynamic). If we choose static, the comments will be rendered along with the rest of the site. Then, every time a comment is added, we have to trigger a Webhook to regenerate and redeploy the site.
There are some inconveniences to this approach. The regeneration and redeployment process may take several minutes, during which time the new comment will not be available. In addition, if the site receives many comments per day, a static approach will require more server processing time, which can become expensive (some hosting companies charge based on server time).
In this case, it makes sense to render the site statically without comments, then retrieve the comments from the live site and render them dynamically on the client side.
For this, it is recommended to use next.js instead of Gatsby. It can handle both static and real-time methods better, including supporting different outputs for users of different abilities.
Back to the GraphQL discussion. Why do I recommend WordPress’s GraphQL API for handling real-time data? I did this because the GraphQL server can have a direct impact on applications, primarily in terms of speed and security.
For a purely static site, a WordPress site can remain private (maybe even live on the developer’s laptop), so it’s secure. And the user doesn’t wait for a response from the server, so speed isn’t necessarily the most important thing.
However, for a live site, the GraphQL API will be exposed, so data security becomes an issue. We have to make sure that no malicious person can access it. In addition, users will be waiting for a response, so speed becomes a key consideration.
In this respect, WordPress’s GraphQL API has some advantages over WPGraphQL.
WPGraphQL does implement security measures, such as disabling introspection by default. But the GraphQL API for WordPress goes a step further and disables a single endpoint by default (among other things). This is possible because the GraphQL API for WordPress provides native persistent queries.
As for speed, persistent queries also make the API faster because responses can be cached via HTTP caching at several levels, including the client, content delivery network, and server.
These reasons make WordPress’s GraphQL API better suited for handling live web sites.
Using the GraphQL API, if. Expose different data for different users or applications
WordPress is a versatile content management system that can manage content for multiple applications and be accessed by different types of users.
Depending on the context, we might need our GraphQL APIs to expose different data, for example.
- Expose some data to paying users, but not to non-paying users.
- Expose some data to mobile applications, but not to websites.
To expose different data, we need to provide different versions of the GraphQL schema.
WPGraphQL allows us to modify the schema (for example, we can remove a registration field). But the process is not simple. Schema changes have to be coded, and it’s not easy to know who is accessing what and where (for example, all schemas will still be available under a single endpoint, / graphQL).
By contrast, WordPress’s GraphQL API natively supports this usage. It provides custom endpoints that can expose different data for different environments, for example.
/graphql/mobile-app和/graphql/website。/graphql/pro-users和/graphql/regular-users。
Each custom endpoint is configured through an access control list to provide field-by-field refined user access, as well as public and private API schemas to determine whether the schema’s metadata is open to everyone or only to authorized users.
These features integrate directly with the WordPress editor, known as Gutenberg. Thus, creating different patterns is done visually, similar to creating a blog post. This means that everyone can generate custom GraphQL schemas, not just developers.
I believe that the GraphQL API for WordPress provides a natural solution for this use case.
Use the GraphQL API if. Interact with external services
GraphQL is more than just an API for getting and publishing data. Just as important (though often overlooked), it can also process and alter data — for example, by feeding it to some external service, such as sending text to a third-party API to correct syntax errors, or uploading images to a content delivery network.
Now, what is the best way for GraphQL to communicate with external services? In my opinion, this is best done with directives that are applied when creating or retrieving data (unlike WordPress filters).
I don’t know how interactive WPGraphQL is with external services, because its documentation doesn’t mention it, and the code base doesn’t provide any examples of directives or document how to create one.
In contrast, WordPress’s GraphQL API has powerful support for instructions. Each instruction in the query is executed only once in total (not once per field and/or object). This capability makes communication with external apis very efficient, and it integrates the GraphQL API into the service cloud.
For example, this query demonstrates translating the titles and summaries of many posts from English to Spanish by invoking the Google Translate API with the @Translate directive. In one call, all fields of all articles are translated together.
The GraphQL API for WordPress was a natural choice for this use case.
Note: In fact, the engine on which the GraphQL API for WordPress is based, GraphQL by PoP, is designed specifically to provide advanced data processing capabilities. This is one of its distinguishing features. For an extreme example of what it can do, see the guide “Send localized communications by user”.
Using WPGraphQL, if. You want a support community
Jason Bahl has done a great job of bringing together the community of WPGraphQL. So if you need to troubleshoot the GraphQL API, you’re likely to find someone who can help you.
For my part, I’m still trying to build a user community around the GraphQL API for WordPress, which of course is nowhere near as good as WPGraphQL.
Using the GraphQL API, if. You love innovation
I call WordPress’s GraphQL API a “forward-looking” GraphQL server. The reason is that I often go through the list of requests for the GraphQL specification and implement some of them in advance (especially those THAT I find somewhat palatable or that I can support with little effort).
As of today, the GraphQL API for WordPress supports several innovative features (such as execution of multiple queries and pattern-naming intervals) provided as opt-in, with plans for more.
Using WPGraphQL, if. You need a complete schema
WPGraphQL has fully mapped the WordPress data model, including.
- Posts and pages.
- Custom post types.
- Categories and labels.
- Custom taxonomies.
- The media.
- The menu.
- Settings.
- The user.
- Comment on it.
- The plug-in.
- The theme.
- Small tools.
The GraphQL API for WordPress maps the data model step by step with each new release. As of today, this list includes.
- Posts and pages.
- Custom post types.
- Categories and labels.
- Custom taxonomies.
- The media.
- The menu.
- Settings.
- The user.
- Comment on it.
So if you need to get data from a plug-in, theme, or gadget, only WPGraphQL can do that right now.
Using WPGraphQL, if. You need to extend
WPGraphQL provides extensions for many plug-ins, including advanced custom fields, WooCommerce, Yoast, and Gravity Forms.
The GraphQL API for WordPress provides an extension to Events Manager, and more extensions will continue to be added after the 1.0 release of the plug-in.
If you use these two methods. Create a block for the WordPress editor
Both WPGraphQL and the GraphQL API for WordPress are currently working to integrate GraphQL with Gutenberg.
Jason Bahl describes three ways this integration can be done. However, because all of these approaches are problematic, he advocates introducing a server-side registry for WordPress that can recognize different Gutenberg chunks of the GraphQL schema.
The GraphQL API for WordPress also has an integrated approach with Gutenberg, based on a “build once, publish everywhere” strategy. It extracts Block data from stored content, and it uses a single Block type to represent all blocks. This approach avoids the need for a proposed server-side registry.
WPGraphQL’s solution can be considered tentative, as it will depend on whether the community accepts using the server-side registry, and we don’t know if or when that will happen.
For WordPress’s GraphQL API, the solution will be entirely up to it, and it’s really already a work in progress.
Because it has a greater chance of producing a working solution quickly, I tend to recommend the GraphQL API for WordPress. However, let’s wait for this solution to be fully implemented (in a few weeks, according to the plan) to make sure it works as expected, and then I’ll update my proposal.
Use the GraphQL API if. Distribute blocks through plug-ins
I realized a truth. There don’t seem to be many plug-ins, if any, that use GraphQL in WordPress.
Don’t get me wrong. WPGraphQL has been installed more than 10,000 times. But I believe that most of those installations were to support Gatsby (to run Gatsby) or tO support next.js (to run one of the headless frameworks).
Likewise, WPGraphQL has many extensions, as I described earlier. But these extensions are just that: extensions. They are not stand-alone plug-ins.
For example, the WPGraphQL for WooCommerce extension relies on the WPGraphQL and WooCommerce plug-ins. If any of them are not installed, the extension will not work, and that’s fine. But WooCommerce chose not to rely on WPGraphQL to work; Therefore, there will be no GraphQL in the WooCommerce plug-in.
My understanding is that no plug-in uses GraphQL to run WordPress’s own functionality, or specifically to power its Gutenberg blocks.
The reason is simple. Neither WPGraphQL nor the GraphQL API for WordPress is a core part of WordPress. Therefore, it is not possible to rely on GraphQL the way plug-ins can rely on WordPress’s REST API. Therefore, plug-ins that implement Gutenberg blocks can only use REST to retrieve data for their blocks, not GraphQL.
The solution, it seems, is to wait for the GraphQL solution (most likely WPGraphQL) to be added to the WordPress core. But who knows how long that will take? 6 months? A year? Two years? Longer?
We know WPGraphQL is being considered for the core of WordPress, as Matt Mullenweg has hinted. But a lot has to happen before then: getting the lowest PHP version up to 7.1 (both WPGraphQL and the GraphQL API for WordPress are required), and having a clear decoupling, understanding, and roadmap for GraphQL’s capabilities.
The full-site editing currently under development is REST-based. What about the next major feature to be addressed in Phase 4 of Gutenberg, multilingual blocks? If not, which feature?)
Having explained the problem, let’s consider a potential solution — one that doesn’t have to wait
A few days ago, I had another revelation. From the GraphQL API for WordPress code base, I was able to make a smaller version that contained just the GraphQL engine and nothing else (no user interface, no custom endpoints, no HTTP caching, no access control, nothing). This version can be released as a dependency on Composer so that plug-ins can install it to drive their own blocks.
The key to this approach is that the component must have a specific purpose for the plug-in and not be shared with anyone else. Otherwise, two plug-ins that reference the component at the same time might modify the schema in such a way that they overwrite each other.
Fortunately, I’ve recently worked out the scope of the GraphQL API for WordPress. So, I knew I could fully scope it and produce a version that didn’t conflict with any other code on the site.
This means that it will work on any combination of events.
- If the plug-in containing the component is the only one that uses it.
- If WordPress’s GraphQL API is also installed on the same site.
- If you have another plug-in installed on your site that also has this component embedded.
- If two plug-ins embedded in the component refer to components of the same version or different versions.
In each case, the plug-in will have its own separate, private GraphQL engine, which can be powered entirely by Gutenberg blocks (we don’t need to worry about any conflicts).
This component will be called the Private GraphQL API and should be ready in a few weeks. I’ve already started working.
So my advice is that if you want to use GraphQL to drive Gutenberg blocks in your plug-in, wait a few weeks and then look at the GraphQL API for WordPress’s little brother, the Private GraphQL API.
conclusion
Although I do have skin in the game, I think I’ve managed to write a mostly objective article.
I’ve been honest about why and when you need to use WPGraphQL. Similarly, I’ve been honest in explaining why the WordPress GraphQL API seems to be better than WPGraphQL in some usage situations.
In general, we can sum up as follows.
- Use WPGraphQL to static, or use WordPress’s GraphQL API to live.
- Play it safe with WPGraphQL, or invest in the GraphQL API for WordPress (for a potentially worthwhile return).
Finally, I want the next.js framework to be rearchitectedto follow the same approach Frontity uses: they can access an interface to get the data they need, rather than using a direct implementation of a particular solution (currently WPGraphQL). If so, developers can choose which underlying server to use based on their needs (whether it’s WPGraphQL, the GraphQL API for WordPress, or some other solution to be introduced in the future) — from project to project.
Useful links
- WPGraphQL: Documentation, download page, code base
- WordPress GraphQL API: Documentation, download page, code base
- “The Gatsby WordPress Integration Workshop” YouTube video with WPGraphQL demo
- The GraphQL API for WordPress is a YouTube video that demonstrates the GraphQL API for WordPress