GraphQL 101: Intro to GraphQL

GraphQL is a query language and a server-side runtime for APIs that prioritizes giving clients exactly the data they request.

Why Does It Matter?

According to Gartner, 83% of all Internet traffic comes from APIs. And while it is not disputed that REST APIs still dominate API implementations. GraphQL is growing in use and expanding across new use cases. Check out the comparison for these four API architecture styles. I used Google Trends to build the comparison chart.

GraphQL is still new compared to REST as illustrated by the current architecture maturity distribution from InfoQ. GraphQL is considered just beyond early adoption. It is clear from GraphQL's momentum and it moving toward a majority that it will be an API that both backend and frontend developers need to know.

History

GraphQL was developed at Facebook as part of their iOS and Android client development in 2012. GraphQL provided benefits to mobile applications by limiting the number of network calls required to deliver data. GraphQL's single endpoint and client control over what and how much data would be requested were performance improvements over using REST which required a new request for each data resource needed by its applications. In 2015, Facebook open sourced GraphQL and in 2018 they published the complete GraphQL Specification. Next in 2019, Facebook and others created the GraphQL Foundation, a non-profit hosted by the Linux Foundation, to provide a neutral home for GraphQL assets and support increased collaboration, infrastructure and community programs.

The Specification

The GraphQL Specification is a document that describes the core components and rules for GraphQL implementations. Just as JSON files are referred to as JSON documents, GraphQL files are referred to as GraphQL documents. There are two types of GraphQL documents: executable documents and schema documents. Executable documents are also called queries and describe data requested and any additional operations that will be performed on the data.

The GraphQL client mostly focuses on making a call to the server using the query and mutation operations. You can think of these as queries are the "reads" of a REST API and mutations provide the other CRUD operations of "create", "update" and "delete".

The Schema document is used to describe the data available from the GraphQL endpoint and is also used to validate a query when a request is made and before the query is executed by the server.

A GraphQL Query Example

What if we wanted to grab some data from the Github's GraphQL server at https://api.github.com/graphql, and get a response that included our Github username? It would look like this.

'# We'll get you started with a simple query showing your username!
query { 
  viewer { 
    login
  }
}

the GraphQL server would provide a response that looks like this.

{
  "data": {
    "viewer": {
      "login": "doc-jones"
    }
  }
}

You probably notice that the query object starts with the word query. This example is a very simple query. If it were part of a larger graph presenting many resources or services it is considered a best practice to give the query a name. For example:

'# We'll get you started with a simple query showing your username!
query username { 
  viewer { 
    login
  }
}

Another interesting observation is that the use of word query is by convention and not required by the specification. It can be helpful when you are new to GraphQL to adhere to these conventions as it will help you read your schema and quickly locate or distinguish between queries, mutations and subscriptions. We have discussed mutations and queries, yet, but these are the three operations that GraphQL provides to retrieve and alter data. More on that in a future post.

Schemas, Libraries and Resolvers

Earlier we mentioned schema documents as being the second type of document included in the GraphQL Specification. The schema defines the syntax of your API. In an API-first approach, a schema will be written as part of designing a GraphQL API. It will then be the source of truth for validating your GraphQL operations: queries, mutations and subscriptions. The Spec doesn't provide rules or guidance on how to store data or which tech stack to use. Those decisions are left to you, the developer.

GraphQL does not provide any direction for what programming language to use. Developers can choose Java (graphql-java) PHP (graphql-php), Scala (Sangria), Python (Graphene Python), Ruby (graphql-ruby), JavaScript (graphql.js), Rust (async-graphql) and more.

The other term you will hear frequently associated with GraphQL is the term "resolvers". Just as an introduction, resolvers are functions that a developer attaches to each field in a GraphQL Schema to return the value of that field. As we will learn in this series, resolvers can be written in any programming language.

Advantages and Disadvantages

Advantages

• The GraphQL Schema provides a single source of truth for applications.
• A request/response is handled in one round trip.
• GraphQL is introspective. A client can request a list of data types available.
• Clients receive the data they requested - no over-fetching.
• Defined data types reduce miscommunication between clients and servers.
• Versioning isn't required. The graph can evolve without breaking queries.
• There are an ever-expanding set of libraries that provide features not available in REST.

Disadvantages

• GraphQL has a significant learning curve as compared to REST.
• It adds complexity to the server by requiring the data query work is done there.
• Depending on how it is implemented GraphQL might require different management strategies than REST APIs, for example in rate limiting (see Github's description of rate limits for its GraphQL API).
• Caching is more complex.

Community

GraphQL has a vibrant and passionate community. There are a couple of key open source projects that invest heavily in the GraphQL community. This list is a sample and not close to being complete.

Apollo - provides open source client libraries and server-side frameworks, educational content, certification, events both virtual and in-person and the largest GraphQL conference annually, GraphQL Summit. They also maintain a thriving discord server for community support.

TheGuild provides some of the most beloved tools (we will talk about this later) and all are open source projects.

There are Meetups globally and I encourage you to search for a GraphQL meetup or presentation near you because chances are there is one.