GraphQL: The API technology to watch in 2018

Let’s say you’re a developer working for a retailer who’s built out a catalog of 250 commerce-related APIs, exposing every granular piece of data (product, category, price, inventory, etc) and functionality (add to cart, calculate discounts, reserve inventory, etc). Say you’re re-designing your website and need to build a new product detail page. Today’s product detail pages need to access data (products, related products, inventory, pricing, etc) from dozens or even hundreds of APIs.

You could always call directly to each of the APIs but for performance (and many other) reasons you don’t want to make hundreds of calls from an end-customer’s browser back to your APIs. You could always write an intermediary layer whose job it is to query all of the APIs, but now you’ve tightly coupled this new layer back to your APIs, which goes against the whole philosophy of API and microservice-based development.

To make matters worse, you practically never want to retrieve an entire object from an API. When you retrieve a product, you probably just want its name, description and a few other pieces of information, though there may be hundreds of other attributes.

This is where GraphQL comes in. Facebook had these exact same challenges, only worse because many of its users are on bandwidth and performance-constrained mobile devices. Imagine the number of API calls to build a user’s Facebook timeline, now imagine performing all of those queries from an Apple Watch over a cellular internet connection. Facebook built specification for how to query for data called GraphQL. GraphQL.org, the home of the project, states that GraphQL is “A query language for your APIs.” Facebook has been using it internally since 2012 and publicly released it in 2015. Since then, it’s quickly caught on and is now used by Twitter, Yelp, GitHub, Intuit, Pinterest and New York Times, among many others.

With GraphQL, you just make a single query, specifying exactly what information you want to retrieve. The GraphQL layer then makes requests to the individual APIs to fulfill the request. As a developer, you get a single response containing everything you need to render your new product detail page. Think of GraphQL almost like SQL, where you can retrieve data from multiple database tables using one query. While GraphQL started with queries, it now supports mutations which allows you to create/update/delete data, again similar to SQL.

The advantages of GraphQL are manifold. As just mentioned, developers can access only the exact data they need, which improves performance and reduces the amount of traffic flowing through your network, which is especially helpful for low-bandwidth environments like smartphones and wearable devices. Another advantage is that developers don’t have to know how to call each API.

In a microservices environment where teams have some autonomy in how they implement things like security, it can be difficult for developers to call dozens or even hundreds of different APIs, each with a slight (or major) variation. With GraphQL, developers don’t have to even know that the APIs exist – they just query GraphQL and that layer does everything for them. GraphQL also reduces coupling between front-ends and back-ends.

Rather than building a separate API and microservice for rendering the product detail page for an Apple Watch (and every other client), you can just make direct queries from your front-end to your GraphQL layer, bypassing queries to these intermediary layers you’d otherwise have to build. Finally, GraphQL pairs nicely with React, which also came from Facebook and is widely seen as the default for front-end development today.

Remember that GraphQL is a specification, not a product. Think of it like HTML, where the World Wide Web Consortium (W3C) defines the specification and then individual browsers are left to implement the code for rendering web pages. In the case of GraphQL, Facebook publishes the specification and individual developers write code that conforms to the specification.

It’s important to note that GraphQL a complement to APIs, not a replacement to APIs. Individual teams still need to build applications and expose functionality over APIs, with GraphQL acting as the layer that developers interact with. GraphQL then interacts with the APIs and deals with security and the oddities of each API.

Like with any technology, there are negatives too. It’s another layer to maintain. The specification is rapidly maturing and could change as it finalizes. Facebook has sole control over the specification and there are some unresolved intellectual property issues that could be bad if Facebook decided to be malevolent. It’s still relatively early in its adoption cycle.

Even with the few downsides, GraphQL is worth evaluating now. It could very well end up being the differentiator that sets your commerce initiatives apart.