We spoke with Jason Bahl, Principal Software Engineer at WP Engine in our latest API Intersection podcast episode. Bahl is the creator and maintainer of WPGraphQL, a free, open-source WordPress plugin that provides an extendable GraphQL schema and API for any WordPress site. Bahl helps reduce friction for developers and site owners who want to use WordPress as a CMS.
GraphQL is an open-source query and manipulation language with a heavy focus on client developer experience. We had the pleasure of discussing REST versus GraphQL and the many benefits of using GraphQL for API development.
While I have nothing against GraphQL, there seem to be so many misuses that make me skeptical about overenthusiasm (not to say that was the case in this episode). At Stoplight, we primarily help companies with designing their platforms around REST/HTTP APIs, so it’s certainly our comfort zone. That said, I’m always up for talking to folks who have expertise in emerging API formats like GraphQL, and the discussion with Mr. Bahl was a great one.
REST or GraphQL?
Until recently, it was very likely that the developers created APIs that were REST APIs by default. As the API landscape evolves, many developers have turned to GraphQL. As I hope to explain, the best solution is often to adopt both technologies, used appropriately to their strengths & weaknesses.
REST stands for Representational State Transfer. It is a ‘stateless and uniform format that decouples the client from the server. REST is initially fairly simple to implement and uses the HTTP transport layer to support creating, reading, updating, and deleting data.’ (GRAPHQL vs. REST, Educative 2022). In it’s simplest translation, that means REST design is about respecting the fundamentals of HTTP, using the same principles that have scaled the World Wide Web across the globe.
For the purposes of this discussion, I accept that there is rarely an API designed that meets all of the REST design constraints perfectly, and the term is used loosely here to address most HTTP-oriented, resourced-based API designs.
“In REST, everything is individual resources. And so if you need nested resources, you have to get the first resource, figure out what the relationships are, then make calls back for the related ones, and if there are subsequent relations after that, you have to do the same thing over and over,” shares Jason Bahl.
Bahl is obviously a big fan of GraphQL. In our conversation, he explained how REST, in his opinion, didn’t offer the same developer experience and ability to maintain code over time that GraphQL offered his team. He emphasizes how REST API calls are very implicit, where a developer can just hit an endpoint and get something back from the server that they can start working with quickly. However, if something on the server changes and your application breaks, it can be challenging to debug that six months down the road, especially if the API doesn’t have good updated documentation.
“On the flip side, GraphQL requests are very explicit, so you actually write the query down to the same field that you want to interact with. And so if something does break, which it probably will, you can at least understand the intent of whoever wrote the code and figure it out a little bit easier,” explains Bahl.
Instead of doing a ton of digging to understand past code decisions, the explicit nature of GraphQL helped his developer team be more efficient and flexible over time. GraphQL also offers the advantage of removing the multiple endpoints issue. Instead, GraphQL has a single endpoint that allows developers to tell the API what they want declaratively. Additionally, one of the other GraphQL benefits is that it can be implemented incrementally or even used as a query wrapper over a collection of REST APIs.
So, Which to Choose? Depends…
When selecting the most appropriate API technology, it always depends on the consuming developer’s use case and their needs. While Bahl is a GraphQL fan, there are plenty of use cases where REST makes sense.
REST APIs are well-served in long-live domains at scale. When defining the core capabilities of a business in a typical microservices strategy, where “the big things” that your business does don’t often fundamentally change, prioritizing structural consistency, independently scalable services, and HTTP-level caching over query flexibility usually makes sense. With this in mind, REST is often less flexible when compared in simple terms to GraphQL, as there’s a tendency to have a more rigid hierarchy of resources, resulting in a greater burden on API consumers.
For developers building customer experiences, the rigid structure in REST APIs can result in some friction & inefficiency, where you only want the data you’re going to display in one call in simple declarative terms. In these scenarios, GraphQL is a truly elegant choice. That said, with the increasing maturity of HTTP/2 tooling, multiplexed calls can make multiple trips to call REST APIs highly performant. However, in API consumer developer experience terms, it’s still a bigger lift for devs than the ease of querying with GraphQL.
In terms of performance risks around GraphQL, the biggest one is a lack of HTTP-level caching support, as everything is a POST (much like SOAP). REST-style APIs should comply with the same HTTP semantics as your browser, meaning that we can do multi-level HTTP caching on GET operations (usually through caching proxies in front of your APIs). In other words, if your API consumers will be retrieving data in high volume, a more REST-oriented design can provide orders of magnitude greater scale than POST-only technologies like GraphQL.
The next GraphQL performance risk is around data retrieval performance. The underlying data stores that your GraphQL API is accessing cannot be optimized for all possible query paths, and the query flexibility that’s so attractive can result in a game of query performance whack-a-mole if the graph is not carefully constrained.
Sometimes Both is the Right Answer
In my personal opinion, a mature API program will use a blend of API technologies appropriate to the consumer use case and data retrieval patterns. The most important factor across those technology approaches is a thoughtful, capability-oriented design approach. This usually starts at the “bottom” of the stack in designing your core domains/capabilities, most often around a REST-style approach. If this aspect of platform design isn’t properly attended to, you might not be able to produce a graph that will make sense anyway.
Most mature API programs today are using REST/resource-oriented design to build the foundation of their platforms. GraphQL is most often used to aggregate/compose data on top of those REST domain APIs to serve specific customer experiences, where its flexibility really shines.
We drink the design-first champagne here at Stoplight and focus on helping our customers design their platform’s foundations with REST APIs. However, if you think we should add GraphQL to our product roadmap, I invite you to submit that on our product board for consideration.
As always, for more insights and tips from industry experts, visit our API Intersection podcast. Thanks, Jason Bahl, for the great debate!
