The representational state transfer (REST) API has served its purpose of exposing application-level information for web services over the last 15 years, but in an industry that’s constantly evolving, there are always new approaches that are popping up and transforming the way we work. Enter GraphQL.

GraphQL is a data query language for APIs that was developed by Facebook in 2012. Unlike traditional query languages like SQL, GraphQL goes beyond just databases. It combines ideas from the world of databases and couples it with web API features to enable developers to build data-rich applications, according to Lee Byron, former engineer at Facebook, who works on the GraphQL project.

After three years under development at Facebook, the company decided to open-source the project in 2015. “When we built GraphQL in 2012 we had no idea how important it would become to how we build things at Facebook and didn’t anticipate its value beyond Facebook,” Byron wrote in a post at the time of the open-source announcement.

Over the last three years, the open-source project has created a strong community of developers, matured, and improved so significantly that the industry has come to take a closer look. As of recently, one of the main motivators for moving to GraphQL has been to replace current REST initiatives.

According to Byron, GraphQL is a different way of thinking about the problem of exposing data.

“People are excited about GraphQL because there are some very real problems that just about everyone building a data rich app runs into,” Byron said in an interview with SD Times. Those problems include getting all the data you need in a reasonable amount of time, and figuring out what to do with the data from the API once it comes back.

Making a case for GraphQL
Hasura, a cloud infrastructure company and GraphQL solution provider, finds that while writing a GraphQL server is a little bit more difficult than a normal server, the benefits are even more difficult to ignore. Tanmai Gopal, co-founder and CEO of Hasura, explained that in a traditional development environment there is too much back and forth between the front-end developer and back-end developer. For instance, for every piece of data, API endpoint, or feature the front-end developer needs, they need to request it from the from the back-end developer first. Once the back-end developer builds it, they need to test it and document it before sharing it back with the front-end developer.

GraphQL eliminates the complexity and back and forth because it enables the back-end developer to just build and present a GraphQL server for fetching data, according to Gopal. That server provides a single API endpoint that front-end developers can make any type of query to.

“At a high level, the front-end developer can basically see every possible API query they could make, and they don’t need to keep asking the back-end developer to give them an API for this use case or that use case. This cuts down the back and forth that is required with traditional development, and accelerates feature development,” said Rajoshi Ghosh, co-founder of Hasura.

Byron explained with REST APIs, there is also tight linking between the concept of a single idea and a URL to load that idea. “That means, you can only load one thing at a time. That becomes a problem when you need all the data for a complicated view. You might have to load lots of different URLs because each piece of data is going to be presented by one URL,” he said.

With GraphQL, there aren’t multiple URLs to learn. There is one single URL and it adds in the concept of a query language. “With GraphQL, you describe the data you need by writing it in the query language, and then you send that query to the one URL. The URL looks over your query, makes sure all the relevant data you need to fulfill the query is available, puts it together in the shape that is expected by the query and returns it back,” Byron said. So with GraphQL, you get all the data you need in a single roundtrip whereas REST has to make multiple roundtrips for each piece of data, Byron added.

Unlike GraphQL, a REST API also has a very fixed set of data, and if the front-end developer doesn’t describe absolutely everything they need, it won’t be there in the end result, according to Byron.

According to Gopal, the mean benefits of GraphQL over REST are:

  • GraphQL helps app developers make more efficient queries as compared to typical REST because developers can fetch (“query”) for exactly the slice of data they want
  • GraphQL helps app automatically discover APIs and associated documentation without back-end developers having to maintain explicit documentation that becomes painful to maintain during frequent iterations. This reduces communication between developers drastically and reduces the tooling and process typically required to share APIs, test APIs & document APIs which is unavoidable with REST.
  • GraphQL community tooling helps app developers validate their API calls before deploying their apps, automatically generates code and reduces the boilerplate typically required to integrate APIs into their apps.

Looking at it from another angle
Uri Sarid, CTO of MuleSoft, an integration platform provider, believes REST and GraphQL are two very different solutions.

“One major advantage of REST APIs, and the reason they won over other approaches such as SOAP (‘web services’) in the enterprise space despite the latter being supported by all the major vendors, is the fact that REST APIs are in fact ‘just HTTP.’ In particular, the common needs for routing requests, for transmitting metadata along with data, for standardized responses, for caching and security semantics that can be reliably shared across a whole host of physical and software components because they are not only standard but also simple — all these and more have been worked out, tested and hardened across millions of servers and sites and clients and applications since the web first emerged,” Sarid wrote in an email interview with SD Times.

“On the other hand, GraphQL is a very specific protocol and set of tools introduced by Facebook to expose data and capabilities as functions, and to query multiple of those functions in one call, asking for and receiving only the data needed by the caller,” said Sarid. “There is no notion of domain-specific nouns and standard verbs — only whatever functions the service decided to offer, and however it decided to represent the data.”

According to Sarid, people who believe GraphQL will replace REST APIs are probably not implementing them correctly. “When done well, RESTful APIs expose a clean, elegant, understandable, and extensible model of any domain. When done poorly, they are little more than remote function calls, and because each function call is a roundtrip on the network, using them to assemble the information or orchestrate the capabilities needed by the client can be difficult and slow. This slowness and difficulty is particularly exacerbated in mobile applications, where the network is particularly precious, and speed of development is paramount,” wrote Sarid.

However, Sarid explained he does believe GraphQL calls attention to a need that is not being met by REST APIs, but he doesn’t believe it will replace REST as a general paradigm for APIs.

According to Sarid, the reasons GraphQL won’t take over REST are:

  • The specific needs of mobile clients aren’t as important in many other contexts. Those needs, whether in mobile or other contexts, may be met by layering querying capabilities on top of REST APIs.
  • REST APIs offer many advantages over GraphQL which are not easily met, even when extending GraphQL. Conversely, GraphQL introduces many problems versus REST APIs
  • The domain modeling built into REST API design, and the resultant exposure of clean domains as APIs, leads to a loose coupling between different domains and different organizations, which is critical to maintaining agility in large networks of applications.
  • There is really only one example of a very large system of applications that has survived, scaled, evolved, and yielded tremendous value over not just years but decades: it is the web itself. The web provides powerful evidence of the benefits of REST that’s stood the test of time; it seems much easier to imagine meeting the needs that GraphQL addresses by building on top of REST, versus recreating all those advantages anew for GraphQL as robustly.

“With GraphQL today, developers must roll their own, bet on one of the emerging open-source but non-standardized solutions, or rely on a proprietary vendor solution,” wrote Sarid.

In spite of all that, Hasura’s Gopal believes over the next couple of years we will see more of a migration to GraphQL. “The benefit of GraphQL over REST is extremely real, and people who are championing for GraphQL have been leaders in the industry for 10 to 20 years,” said Gopal. “GraphQL is going through a golden age. By this time next year, we will know what the landscape for replacing REST will be and I expect we will see much broader adoption.”