Introduction to GraphQL

If you're new to GraphQL, skim this page for a brief introduction on what it is, and how it's different from other types of APIs. If you're already a pro, feel free to move along.

About GraphQL

GraphQL is a new way of thinking about fetching and manipulating resources across the internet. Implicit in GraphQL is the understanding that all resources in a system are interconnected peices of a larger graph, and that you should be able to read from multiple parts of the graph at one time in a way that is driven by the client, not the server.

What does that mean? Here's an example:

Suppose you have a podcasting API where you aggregate RSS feeds of popular podcasts and publish information about them that people can search and access. There might be a few resources that you manage in your system, such as:

1. Publishers
2. Podcasts
3. Podcast Episodes
4. Podcast Hosts

Everything is part of a larger graph

Although these are four distinct resources in your system, these resources are inter-related. A Publisher might have many Podcasts, a Podcast might have many Podcast Episodes, and a Podcast Episode will have at least one Podcast Host. You might even design your database schema around these relationships.

Additionally, each one of these resources has a number of attributes, like a name, or a date for a Podcast Episode.

If you wanted to expose this data programmatically to developers, you'd traditionally build a REST API to do it.

For example, you might build the following REST API to expose information about the podcasts in your system.

1
2
3
4
5
6
7
8
9

GET /api/publishers               # List publishers
GET /api/publishers/:id           # Show details about publisher X
GET /api/podcasts                 # List podcasts
GET /api/podcasts/:id             # Show details about podcast X
GET /api/podcast-episodes         # List podcast episodes
POST /api/podcast-episodes        # Create a new podcast episode
DELETE /api/podcast-episodes/:id  # Delete a podcast episode
GET /api/podcast-episodes/:id     # Get details about episode x
GET /api/podcast-hosts/:id        # Get details about host x

Now, imagine that you want to build an app that allows for simple navigation of podcasts. The app opens with a list of publishers. Clicking into one reveals a list of their podcasts, then clicking into that reveals a list of their episodes, etc. This API would power this easily. You'd make one API request per screen depending on what resource you wanted to view.

Now, this is obviously an oversimplified and contrived example, but it's illustrative of two problems you'd have building your app with this API:

What if you wanted to change your navigation, so that the first screen was list of a 25 recent podcast episides, and in each row you'd show the name of the podcast, the name of the episode, and the name of the host with their photo. How would you do that with the API that you have? You'd have to:

1. Make 1 request to the /api/podcast-episodes to get a list of podcast episodes with names, streaming URLs, as well as podcast and host ids.
2. Make 1 request per podcast episode to /api/podcasts/:id to get details about the podcast like it's name and image.
3. Make 1 request per podcast episode to /api/podcast-hosts/:id to get the host's photo.

If you're displaying 25 episodes, that's 51 API requests you've made to render one screen. Even if you could do 2 requests in parallel and each one took only 100ms, that's ~2.6 seconds of waiting time before your app is usable. That's a lot of time for a fickle user who could just go back to Apple Podcasts (even though everyone knows Apple Podcasts is the worst one).

The second problem with this paradigm is how much extra data you've had to fetch that you didn't need. You had to make 25 API requests to /api/podcasts/:id just to fetch each podcast's name and image, even though the API probably returned a lot of other good info to you, like it's air date, and a list of all its episodes. Then, you had to do the same thing with /api/podcast-hosts/:id just to get the image URL of the host, even though you probably also got back the name of their alma mater and what Malcom Gladwell book they're reading right now.

All that extra data isn't free, the server had to load it for you. Extra loading means extra latency, just to fetch data that you end up throwing away once you get it back.

Let's reimagine our resources above as an interconnected schema. It might look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

type Publisher {
  name: String
  podcasts: [Podcast!]
}

type Podcast {
  name: String
  publisher: Publisher
  airDate: Date
  imageUrl: String
  description: String
  episodes: [PodcastEpisode!]
}

type PodcastEpisode {
  name: String
  airDate: Date
  description: String
  streamUrl: String
  imageUrl: String
  length: Int
  podcast: Podcast
  host: PodcastHost
}

type PodcastHost {
  name: String
  imageUrl: String
  almaMater: String
  currentGladwellThinker: String
  podcastEpisodes: [PodcastEpisode]
}

Given that we know the schema, GraphQL allows us to construct queries that selectively grab information from objects in the graph. We could write one GraphQL query to replace our 51 calls above:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

query HomeScreenQuery {
  topEpisodes {
    id
    name
    streamingUrl
    airDate
    podcast {
      id
      name
      imageUrl
    }
    host {
      id
      name
      imageUrl
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

{
  "data": {
    "topEpisodes": [
      {
        "id": "f0e2797f-3cf0-45d1-84f7-845155282f0d",
        "name": "Is Ukraine Turning the Tide in War?",
        "streamingUrl": "https://assets.nyt.com/ukraine.mp3",
        "airDate": "2022-09-13T08:00:00Z",
        "podcast": {
          "id": "bd250a48-4327-42f1-97a3-90f9ebffd4e5",
          "name": "The Daily",
          "imageUrl": "https://assets.nyt.com/daily.png",
        },
        "host": {
          "id": "616c0559-5386-4746-b6ca-b9e90ba8ff49",
          "name": "Michael Barbaro",
          "imageUrl": "https://assets.nyt.com/mike.png"
        }
      },
      ...
    ]
  }
}

You can think of GraphQL almost like a hyper-targeted SQL query, pulling out just the data you need.

Not every type of API will benefit from GraphQL, but we believe that financial datasets especially benefit from a data access layer with a highly flexible query language. Financial datasets can be quite large, and the applications using this data are quite varied in use case and end-user expectations. No REST API would be able to accurately predict and model for every use case. GraphQL allows developers the flexibility to prototype and scale applications quickly and not have to think about building out their own data access layer.

GraphQL is definitely not a silver bullet, and we're by no means GraphQL maximalists, but we think it's a great innovation for external developer APIs that offers a ton of flexibility (as shown above) and a few other key benefits:

1. GraphQL moves the performance optimization burden from client to server. The server has the opportunity to optimize database requests based on the fields requested.
2. GraphQL is self-documenting and easy to explore. Check out the playground to give it a whirl. (We didn't even build this, it's built into our GraphQL library, Apollo!)
3. It has great community adoption and is well-supported by libraries and frameworks.
4. It's incrementally adoptable. You can start replacing your REST APIs with equivalent GraphQL APIs in your app without doing a big-bang rewrite.

🎓 Learn more

1. Apollo Client is the canonical GraphQL framework, and the one that is most well-adopted in the community. We recommend Apollo Client for any javascript-based app, such as web apps or React Native apps.
2. GraphQL Codegen is a fantastic tool for generating Typescript types based on GraphQL schemas you consume. Read more about generating types from the Yuzu schema here.

1. Apollo iOS Apollo iOS offers the same benefits to native mobile apps that Apollo Client does for web apps.
2. Apollo Kotlin Apollo Kotlin powers GraphQL integrations in Native Android and Kotlin-based JVM apps.

Check out awesome-graphql, the best repository for discovering great community tools built around GraphQL.

graphql.org is the definitive source for in-depth learning about the GraphQL spec and covers much more than what's covered here.