Should you use GraphQL with headless WordPress?
Alex Moon on
Table of Contents
Tech comes and goes, and there has been some great discussion in the last couple of years on whether many of us should actually be using GraphQL. I tend to agree with much of the discussions despite having become a developer as GraphQL was becoming the new hot thing. I have also invested much of my time and energy into tools like Gatsby and WPGraphQL that were built on this technology.
Background
If you haven’t heard the conversations Harry Wolff has a great video explaining the topic.
I’ll summarize his points. In its favor, GraphQL is really great at 2 things:
- Types (and thus introspection and associated tooling)
- Choosing the exact data you need and never over/under-fetching
These points hold true and are great benefits to using GraphQL, but these come at some expense.
The drawbacks on the other hand exist because GraphQL was designed to make building front ends easier. Because of this, it shifts that difficulty to the API and the back-end developer. Thus building GraphQL APIs is fundamentally much more difficult in several ways:
- The complexity of schema design and various GraphQL features: type system, persisted queries, subscriptions, etc
- N+1 is moved to the backend and can be harder to detect by front-end developers
- Caching is hard due to using
POSTby default - Complex client libraries
All of these things have possible solutions, but these all take learning, work, and more complexity. Harry makes it clear that GraphQL is great. But it’s a solution designed and built by Facebook for Facebook scale problems and you probably don’t have those. Most of us don’t, I hedge to guess.
Is GraphQL dead?
No, GraphQL is not dead. If you were choosing to build an API from the ground up to deploy your website REST would probably be the better decision for a variety of reasons. But if you’re debating using WPGRaphQL vs the WP REST API you’re not building from scratch. I believe strongly that shared API implementations like WPGraphQL are a great use case for GraphQL. They provide the benefits of GraphQL to developers who choose them and offload most of the complexities of building a GraphQL API to the project maintainers. Let’s talk about why this is the case.
The complexity problem
I agree 100% with these arguments and how they make doing GraphQL hard. The complexity of building a good GraphQL API is no small task. But because the API is implemented by project maintainers you don’t need to be a Relay expert or understand the intricacies of data fetching from the WP database. You are only consuming an already-built API. You may add custom post types or fields but WPGRaphQL handles integrating those for you through plugins like ACF. These plugins optimize fetching and abstract the hardest parts of building a GraphQL API.
To be sure, understanding how to consume and use a GraphQL API can still be more complex than a REST API, but this is still significantly less complex than knowing how to implement those same things. We can all eat a great meal, but we can’t all cook one.
Solving N+1
The N+1 issue on GraphQL backends is real, and Jason and the other WPGraphQL maintainers work hard to make sure WPGraphQL stays performant. By the way, the recommended solution for this problem is caching between your GraphQL resolvers and your database. WordPress provides an Object Caching API that WPGraphQL uses out of the box if you have a cache like Redis configured.
There are some observability challenges yet to be solved concerning performance and how developers are structuring and designing their GraphQL queries for WP that can’t be solved by the project. But if my conversations or Jason’s own tweets are any sign, WPGraphQL might be seeing some new solutions that are helping enabling developers to directly understand and solve their performance issues.
Client Caching
Client caching is a real problem in GraphQL. Companies like Stellate have built whole products around this issue. The cool part is that once solved caching can be even better than many basic REST caching solutions. The WPGraphQL community has WPEngine thank for helping release the WPGraphQL Smart Cache plugin. This plugin does all the hard work of caching queries either in an object cache, or network cache. It can also enable persisted queries which are the gold standard for GraphQL caching.
Yes, GraphQL caching is hard, and once again the maintainers have taken on and solved this problem for all of us. As consumers of the API we install a plugin, maybe do some integration work with our CDN/hosting provider and we reap the rewards without having to know the gritty details of implementation.
Client Complexity
This last point is the hardest one for maintainers of projects to solve for WPGraphQL users. Luckily, we’re not without solutions here. Once again, WP Engine is helping solve this problem by building the Faust project. Faust provides a client, helps with auth, and so much more…you should really check it out.
The Faust team is doing the hard work of integrating a GraphQL client into React/Next and providing great defaults and a simple APK for us all to use. This can’t solve all the complexity, but it once again gets us a couple of steps closer.
Conclusion
There’s much more to be said on the topic of choosing GraphQL vs REST in the headless WordPress world. The good news is I already wrote on that topic in a recent guide called REST vs GraphQL API. I believe that GraphQL is a great option even for most of our non-Facebook scale issues.
That said if you’re looking to do some highly complex data structures the WP REST API might be a better place to implement these unless you are familiar with implementing a GraphQL server. Personally, I use a mix of GraphQL and REST and there is nothing wrong with this. For example, I find GraphQL mutations a bit cumbersome for basic features. I’ve chosen to use REST API endpoints for implementing forms on this site. It makes things dead simple. On other sites, I’ve used mutations for comments. Pick, choose, mix, and match. In the end, pick your poison and remember your tech stack decisions aren’t a personality and can always be changed.