An Introduction to GraphQL

GraphQL is a protocol for communicating with APIs.

API stands for Application Programming Interface. These are the digital tools that software developers use to build their sites, apps, and services. Highly capable APIs accelerate teams towards success.

Developers communicate with an API using one of several possible protocol conventions including SOAP, REST, and JSON-RPC. We should now add GraphQL to the list. It’s relatively new, and if you don’t know about GraphQL, use this article as your introduction.

Signaling the Future

A recent internal Sabre survey of software developers asked about the good qualities of APIs. We found that 32% of our respondents believe that GraphQL represents the future of API design. Does that number surprise you? Do you think it would be higher or lower at your company?

The interest in GraphQL by our survey’s engineers is impressive. According to a Wikipedia entry, Facebook invented the GraphQL API protocol in 2012 and introduced it to the world in 2015. We often note how fast technology moves, but this is quick, even by Internet measure.

I’m embarrassed to admit that I’ve never coded to a GraphQL API. I’ve used dozens of REST ones. I’ve created a few still being used in production. All of that is good, but it’s time for me to learn something new.

QL Means Query Language

GraphQL is a way for service providers to establish how programmers call their APIs, but it’s something more than that. How does GraphQL achieve its unique perspective? The hint is found in what QL stands for – “query language.”

We can view the query language from both sides to understand better what that means.

• Frontend perspective: it’s a way of asking for attributes from data objects
• Backend perspective: It’s an execution engine returning results matching the query

Programmers often think of APIs as user interfaces into reading and writing data. REST-based APIs clearly define resources and actions that can be done on them. Getting enough data to build a screen, or go through a typical user workflow, might demand that an app makes several API calls.

Most of those API calls might be made to a standard provider. Then the client app must filter through all of the data to find exactly what it needs. Bundling together several API calls can be time-consuming to execute, prone to network error, and demand more complicated business logic.

GraphQL helps reduce those pain-points. How? By allowing programmers to write a query resolving all the needed data through a single request call, even if the information is hierarchical.

In other words, it can combine several related resources that were usually kept separate – separated, for example, by a RESTful architecture.

This is a convenient way for developers to get all the necessary data without making multiple API calls. This can simplify the logic, reduce exposure to errors, and improve mobile app performance while communicating across relatively slow cellphone networks.

Precise queries also guarantee that clients won’t receive too much data from an overly “chatty” service.

Developers Need Documentation

Listening to developers has taught us one thing for sure: they need documentation to learn how to use APIs. It could come in the form of a detailed reference, tutorial, screencast, or sample code, but it must be available.

If you consider APIs are like products, you might think about products you’ve recently bought. Didn’t they come with some form of instructions? They might have been simple, they could have been implied, but products usually come with instructions. Here’s a fundamental problem. Programmers create APIs, and programmers famously hate writing documentation. You might think this makes life difficult for others to adopt and consume new APIs. You are correct.

Industry best practice for making REST APIs suggests moving documentation as close as possible to the design of the APIs. There’s no better example of that trend than looking at the OpenAPI definition (AKA Swagger files).

Design-Driven APIs

Modeling a REST API in the OpenAPI design specification provides for writing schema definition that includes: attribute name, data type, example value, and most significantly, description. Standalone documentation websites can be generated from the data file. A process like that helps foster a culture of self-documenting APIs.

Documenting an API in this manner has nothing to do with REST itself. Anyone can build REST APIs without using OpenAPI and skip writing proper documentation. Design-driven APIs using OpenAPI files requires discipline. It’s directly related to how a team decides to work together in the service of a fantastic user experience. In this case, developer experience (DX).

GraphQL embraces documentation from the start.

Describing a GraphQL schema provides attribute names, data types, and description. Server implementation is generated from such a schema. A design-driven attitude is essential to building GraphQL APIs.

APIs implementing GraphQL can provide an interactive UI called “GraphiQL.” It serves as a kind of interactive development environment (IDE) allowing developers to write requests to the API quickly. Responses to requests are returned in this playground-like environment. Additionally, it surfaces up documentation from the API definition. Documentation includes attributes names, data types, and descriptions.

GraphiQL makes the efficient discovery of a new API easier. It might be more fun too!

Just the Beginning

What I’ve learned about GraphQL tells me its creators were curious about how to set up a user interface allowing developers to control better what they request and receive.

At the same time, GraphQL originators must have wanted to enable API makers to evolve their offering to observe how their APIs are used and to update them without breaking legacy consumers.

For example, I should be able to audit queries sent to my GraphQL API. Then I can measure how often queries ask for a particular attribute that’s offered. Discover available attributes and decide if it’s time to improve, or remove them.

You’ll discover many more interesting capabilities are built into GraphQL. Review these additional concepts as time permits:

• Variables
• Arguments
• Fragments
• Mutations
• Directives

API Future Design

Deciding what API protocol is best for your company’s customer-facing strategy could have been easy a few years ago. One might say: evolve from SOAP towards REST or start with REST. Internally-facing APIs have more options such as gRPC, JSON-RPC, and varieties of microservices.

GraphQL is a contender for best API protocol of the future. Especially for customer-facing, externally-hosted, product-minded APIs. Add it to the evaluation matrix as you decide your ongoing strategy.

Invest time into experimenting with GraphQL. See what it looks like as a provider. See how it feels like a consumer.

Additional References

Make use of these other resources if you want to learn more about GraphQL:

• The GraphQL Foundation
• Facebook Engineering blog post announcing GraphQL
• A Working draft of the specification
• Example Star Wars GraphQL API
• Full-stack tutorial learning site
• A weekly newsletter covering GraphQL
• The OpenAPI specification