GraphQL and REST Can Coexist, Author Will Lyon Says

The REST acronym, more often than not, means Representational State Transfer. And yes, that phrase has always been something of a stretch. Red Hat, for its part, asserts REST is really a set of constraints on how an application uses an API to address other software. It’s a way to ask, “How are you?” and get an answer that makes sense.

Yet you’ve probably already seen the comparisons being made, where vendors characterize GraphQL as, for example, “a more efficient, flexible and powerful way of working with APIs than REST,” and scoring “a few brownie points over REST.” Back in February 2019, marketing platform Crystallize publicly declared, “We have now killed off our REST API entirely and replaced it with GraphQL. Performance and developer experience are the main drivers.”

You’ve even seen similar head-to-head matchups being refereed here in The New Stack. Jessica Wachtel called GraphQL “better for complex systems and microservices” than REST. And Richard MacManus chronicled how e-commerce platform Shopify transitioned from REST to GraphQL, from its perspective, mainly because the REST scheme it had been using for its APIs would return unstructured JSON instead of values that could be mapped to strongly typed variables.

Perhaps most compellingly of all, when Facebook first proposed GraphQL in 2016, GitHub and others adopted it with, as GitHub itself characterized it, the explicit intention of dumping REST.

However, if REST is more of a methodology and GraphQL is, as its maintainers. . . well, maintain, “a query language for your API,” then a head-to-head match between the two wouldn’t be fair, would it? Aren’t they two separate weight categories? Maybe, unless GraphQL isn’t really a query language per se — that is to say, unless it belongs more to the REST category than the SQL category.

REST Specifications Lack Specificity

“The first thing to understand is that there isn’t a clear definition of what REST is,” remarked Will Lyon, a developer advocate with graph database producer Neo4j. Lyon is the author of “Full Stack GraphQL Applications with React, Node.js, and Neo4j,” just off the press from Manning Publications.

“Typically we think of REST as, ‘I have an endpoint that maps to some resource,’” Lyon explained. “So if I have movies and actors, I have a “movies” endpoint, and then I have another endpoint for “actors,” and that maps to some resource. But the way you implement that REST API can be very different — up to the developer.

“There’s no REST specification. So you have everything from just an endpoint that’s returning some JSON, to a JSON API, to the fullest, most complete version of REST: HATEOAS (Hypermedia as the Engine of Application State). There’s really the spectrum of what REST is. That’s not the case with GraphQL.”

So the Shopify and Crystallize transitions, and others like them, weren’t really migrations, as Lyon perceives them, or even the killing off of anything besides inefficiencies. Moreover, they may have been examples of systematic tightening of the protocols and constraints that their REST API should have had from the outset, had there been a specification to match the goals of the methodology.

“One of the beauties of GraphQL is that it’s data layer-agnostic,” Lyon continued. “I can build a GraphQL API on top of any data layer, multiple data layers. I can fetch data from databases, I can even build GraphQL APIs on top of other GraphQL APIs, or on top of REST APIs. So REST and GraphQL are not mutually exclusive. I can use them together by building a GraphQL API on top of a REST API, as a data source.”

👁 Image

Lyon cited the recent the 2022 State of GraphQL Survey. When some 1,489 respondents were asked, “Which kind of data sources are consumed by your GraphQL APIs?” 26.8% of respondents answered REST APIs, with Swagger and OpenAPI listed as examples. It was the No. 2 answer behind databases with 42.5% of respondents.

For more than one-quarter of the survey’s respondents, GraphQL is a way to do REST, not a method of replacing REST.

Putting the either/or Issue to REST

The first enterprises to take the step of adopting GraphQL starting in 2016, Lyon told us, were not typically known for being early adopters of unproven technologies. The wave of uptakes for GraphQL was only feasible, he believes, by enabling itself to be adopted without upheaval. Rather than a “lift-and-shift” approach, these first adopters simply bolted GraphQL onto the APIs they had. And they worked.

“It’s important to understand that distinction that GraphQL and REST are not mutually exclusive,” said Lyon. “There’s a place for both. REST APIs can actually help you build and expose GraphQL to your organization.”

Suppose you have a database query that hits on three elements that share relationships: for example, known pathogens, known treatments and known side effects. With a common REST API implementation, this query could hit three separate endpoints. They’ll all be dependable connections. But with this level of separation, they’ll be slow. The second set of data retrieval calls will follow the first set, and the third set will follow the second, in cascading fashion. But because the retrieved data will not be processed until after all the calls have been resolved, the application will always place one more call than the total number it could possibly require — the classic n + 1 query problem.

“We need to be mindful of the performance implications we have, as we put GraphQL on top of other data layers,” Lyon remarked. “It’s not magic. There’s work to do there.” That work may not be possible with everyday REST implementations where no protocols have been put in place, and no best practices are being implemented. It’s this mess that organizations dump when they say they’re dumping REST for GraphQL.

Ask Lyon Yourself

Lyon plans to dive deep into the topic of GraphQL, including demonstrating how to connect applications to graph databases using solid, dependable GraphQL APIs, during a free, live webinar with Scott Fulton on Thursday, Oct. 13 at 2 p.m. ET / 11 a.m. PT. He’ll also be presenting a live session entitled “Making Sense of Geospatial Data with Knowledge Graphs” during the NODES 2022 virtual conference on Wed., Nov. 16, produced by Neo4j. Registration is free.