Get in touch
Engineering

What Do You Need to Know About GraphQL?

Here's why better API design matters.

If you interact with teams building software, or you sit within earshot of software engineers, you’ve probably heard them talking about GraphQL. Developers get pretty hyped up about new technologies, especially ones that help them build software faster and with fewer bugs. But what is GraphQL, and should you care? In our work building software for our clients, more and more frequently we’ve been recommending and adopting GraphQL. Here’s why.

The Origins of GraphQL

Back in 2011, the smartphone revolution was in full swing. With the introduction of the iPhone and subsequent Android ecosystem, Facebook shifted significant focus into optimizing their mobile experience. That’s when Facebook’s engineering team faced a problem: Mobile phone data connections had high latency and low bandwidth, and that resulted in a slow user experience.

To render the Facebook News Feed, for example, a mobile device would need to make several requests for different kinds of data to the servers, like: “Get me all the latest stories for this user’s feed. Okay now for each of those, get the comments associated with them. Now for each comment, get me all the replies and the name and photo of the person who posted them.”

All these different requests resulted to several seconds of load time, which meant impatient users spent less time on Facebook. To solve this problem, Facebook engineers set out to define a way to request all the data needed to render a screen in one shot. The result was a new query language and specification called GraphQL.

What Is GraphQL?

At its core, GraphQL is a query language (QL) for APIs. It lets apps like the ones on your phone or your web browser to ask for exactly the data they need from the server–no more, and no less–and receive it all in a single request, so things like your news feed show up fast.

In GraphQL, everything revolves around a schema, which represents all the data in your system and what type of information it is. For example, a news story headline is a string of characters, but total number of likes is an integer.

In GraphQL, data is represented as a graph, which means each piece of data is related to the others in a meaningful way. For example, the total number of likes is related to a post. Another total number of likes is related to a comment on that post. Using this graph, data engineers can model complex relationships in a declarative way, which ensures no one will mistake the total likes on a comment for the total likes on a post. This reduces errors, and makes it easy for engineers to quickly understand what data is available from a GraphQL API and build against it.

After they used it in production for several years, Facebook open-sourced GraphQL in 2015, and it was met with a tide of enthusiasm. It turns out GraphQL solves a lot of problems beyond fetching data on low latency mobile connections.

The GraphQL ecosystem has exploded in innovation and found many uses throughout the industry. Companies large and small have adopted GraphQL, including companies like Yelp, Intuit, and GitHub.

If Facebook and GitHub Use GraphQL, Should My Team?

When adopting any new technology, it’s important to consider the benefits and drawbacks of it, and what they mean for your team. At Postlight, we work with our clients to design backend services that best serve their needs.

Over the last few years, we’ve used GraphQL to power all sorts of apps, from an email client to CRMs to content management systems. As we build and ship GraphQL backends to production, our confidence in the long term viability of GraphQL continues to increase. GraphQL is also appearing in more of our open source projects. Glide helps developers rapidly prototype Salesforce integrations using GraphQL, and our WordPress + React Starter Kit now offers GraphQL out of the box.

When we compare GraphQL to other API designs, one of the most noticeable differences we see is that GraphQL tooling increases engineering productivity and time-to-market. Tools like PostGraphile help engineers leverage hard-won SQL knowledge to produce a consistent and powerful GraphQL API based on their relational data model. For a more traditional application server environment, Apollo Server is great for applications that talk to multiple data sources or internal services.

At Postlight we build many frontend projects with React. Once our backend teams have established part of the data model, tools like Apollo’s excellent React client have the frontend engineers executing queries within minutes. They may also fire up GraphiQL to explore the schema and execute queries. We’ve also adopted the concept of end-to-end types using TypeScript. End-to-end types expose statically-typed GraphQL interfaces directly in a frontend codebase so that incorrect queries and type errors are a thing of the past.

Along with engineering productivity advances, GraphQL has also increased the consistency of backend services. Because GraphQL represents data as a statically-typed graph, resources are consistent and always return what the client asked for. GraphQL has also helped solidify best practices around complex API design problems like pagination. Frontend and mobile developers are spending less time creating or learning bespoke pagination interfaces or fighting with inconsistent API endpoints.

So Is GraphQL a Silver Bullet?

Not so fast. I’ve painted a pretty picture of GraphQL so far, but it’s not without challenges. If we take a look back at history, it’s interesting to see how GraphQL differs from other API designs. For sake of time, let’s focus on the most ubiquitous network API design–HTTP REST APIs.

REST became extremely popular due to its resource-oriented design and simplicity. REST heavily leverages HTTP’s semantics for how it works, while SOAP and other designs before it were transport-agnostic. Relying on HTTP has some drawbacks but also a lot of benefits. For example, a well designed REST API can be cached using powerful HTTP caching strategies that can lead to low-latency cached content close to the end user. GraphQL uses the POST HTTP method by default, which is not typically cached in the same way. In order to utilize some of these advanced HTTP caching strategies the community has come up with techniques like Automatic Persisted Queries and a larger reliance on client-side caching.

GraphQL also introduces some complexity into your system when resolving data from an API request. GraphQL requires code to parse and execute a query and logic to map that query to underline data stores or services. REST API endpoints, on the other hand, can be lean and small. For some projects, that maybe the right choice. Companies like Airbnb are facing (and helping solve) problems in this area and sharing the results with the community.


All in all, we’ve been pretty happy with the increased productivity and benefits of the GraphQL ecosystem. Want to discuss the pros and cons of API design? Drop us a line [email protected].

Aaron Ortbals is a Partner and Director of Engineering at Postlight.

Story published on Oct 16, 2019.