Why Shopify Favors GraphQL over REST for Its APIs
GraphQL, a query language for APIs and a server-side runtime for executing those queries, has become one of the most popular ways for web applications to fetch data. It’s increasingly a go-to solution for Single-Page Applications (SPAs), serverless offerings, Jamstack frameworks, and other modern applications. Most importantly, it’s become the technology of choice for building APIs for some internet companies — in many of those cases, usurping the traditional REST method of fetching data.
The “QL” part has led to direct comparisons to SQL (in an excellent introduction to GraphQL for The New Stack, Fikayo Adepoju wrote that it’s “like SQL, but for the front end”). It’s definitely a query language, so the SQL comparisons are valid. But it’s the comparison to REST that I’ll focus on here. How is GraphQL being used today that would’ve required REST APIs in the recent past? What are the pros and cons, versus REST? Plus later in this column, I’ll look at Shopify’s adoption of GraphQL as an example of how it’s being used in the industry.
GraphQL vs. REST
The fundamental insight that led a team at Facebook to create GraphQL in 2012 and release it publicly in 2015, was that data for modern web applications increasingly require a graph structure for optimization — particularly in mobile apps. The inspiration for GraphQL for Facebook was the transition of its mobile applications away from HTML5 and into native applications on iOS and Android (context: in the early years of the smartphone, Facebook tried to route around app stores and create mobile web apps instead of native apps; it ditched this policy in 2012).
To make the move to native apps, Facebook found it needed “an API data version of News Feed — which up until that point had only been delivered as HTML.” This led to a key insight, as GraphQL co-creator Lee Byron explained in 2015 (emphasis mine):
“We don’t think of data in terms of resource URLs, secondary keys, or join tables; we think about it in terms of a graph of objects and the models we ultimately use in our apps like NSObjects or JSON.”
The biggest difference with REST is that just one trip to the server is needed in GraphQL, which makes the data fetch faster. The response to a GraphQL query is sent back as JSON. In the REST model of fetching data, multiple round trips to the server are often needed to get all of the data an application requires — so it can be slow, especially on a mobile device.
The other key benefit of GraphQL is that the client specifies precisely which data it requires. For example, if it’s for a product page on an e-commerce app, the client can specify that it wants to receive only the name of the product, its price, its customer rating, and its availability. All other data about that product (for example, its technical specs if it’s an electronic product) are not downloaded unless specifically requested. Whereas with a REST API request in the same use case, the server might send back a whole bunch of unnecessary details about a particular product.
This specificity in GraphQL is possible because of the schema, a kind of contract between the server and the client that defines the data types. So GraphQL does require more work up front, using the Schema Definition Language (SDL). But once that work is done, there is a lot more flexibility in GraphQL than in REST.
Shopify’s Adoption of GraphQL
Sticking with e-commerce as a use case, one of the biggest proponents of GraphQL nowadays is Shopify. In May 2018, Shopify offered its most-used REST API, the Admin API, in GraphQL. Since that time, GraphQL has “become Shopify’s technology of choice for building APIs,” according to its developer website.
In a post on its engineering blog earlier this year, Shopify senior developer Maryam Fekri explained that one of the “pain points” Shopify had with REST was mapping data from the server to the client (or vice versa):
“When working with REST endpoints these mappings are basically matching statically typed code with the unstructured JSON responses. In other words, mobile developers are asked to hard code the type of a field and cast the JSON value to the assumed type.”
This meant that when Shopify had to make a change to one of its REST APIs, external developers would need to update their code accordingly. But with GraphQL, because data is strongly typed (meaning each type is predefined in the schema) the client is always in sync with the server when it comes to mapping data. As Fekri put it, “There are no more statical types in your mobile application and no JSON mapping with the static data types in the codebase.”
Although Shopify is now all-in on GraphQL for building APIs, Fekri cautioned that “on the client-side, we have to consider the costs of a query we build.” In other words, you can’t make your queries too complex. For this reason, Shopify has a limit on what it terms “calculated query cost.” Fekri explained it this way:
“Each field in the schema has an integer cost value, and the sum of all these costs will be the cost of the query we build on the client-side.”
Shopify has a points-based formula to define the “calculated query cost” — so for example, you might only be allowed to accrue 1000 points within 60 seconds.
Conclusion
It’s not that Shopify has completely abandoned REST APIs — it still has REST versions for basic functionality such as admin, billing and inventory. But there are some Shopify APIs that are now only available in GraphQL, such as the Partner API and Storefront API. As for the core Admin API, the GraphQL version is the favored one, as the following note on its API overview page makes clear:
“The Admin API is accessible using either GraphQL (recommended) or REST.”
I should add that REST is still the most-used API format in many other companies, including prominent API public companies Stripe and Twilio. So this is not a “death of REST” type article; REST is alive and well. But, GraphQL is growing quickly — and at least at Shopify, has already proven it’s a worthy replacement for REST.