GraphQL: A Primer

GraphQL. The latest and greatest in the realm of APIs. Well, that’s what it is right? Not exactly. GraphQL (Graph Query Language) is a language that is used to query data from APIs. This means, as developers we can define the structure of data we need.

Why GraphQL?

GraphQL is designed to make the job of a developer easier. Developers can define the data they need without changing configurations in the backend. This is huge. Compared to a REST API, a well structured GraphQL server would avoid over or under fetching.

Before working with GraphQL, there is some terminology we need to learn. I’m going to summarize quickly from the GraphQL documentation.

Query: GraphQL queries are used to fetch data from the server. With a query, we can define the structure of the data we want. The REST equivalent to this is a GET request.

Mutation: GraphQL mutations are used to mutate (i.e change) data on the server. The REST equivalent to this is a POST request.

How can we make a basic query in GraphQL?

To show that we will be using the SpaceX GraphQL API. Every GraphQL API comes with a GraphiQL (pronounced Graphical) console. This makes working with GraphQL simple and intuitive.

An example of a GraphiQL console.

Below is an example of a GraphQL query. We are fetching a list of launches from the database. From each launch object, we want the mission name, launch date, launch site, and rocket object.

{
  launchesPast(limit: 3) {
    mission_name
    launch_date_local
    launch_site {
      site_name_long
    }
    rocket {
      rocket_name
      first_stage {
        cores {
          flight
          core {
            reuse_count
            status
          }
        }
      }
    }
  }
}

It’s that simple. We just defined the data we want to see. Below is the payload. Try running that query in the GraphQL console for yourself.

{
  "data": {
    "launchesPast": [
      {
        "mission_name": "GPS III SV04 (Sacagawea)",
        "launch_date_local": "2020-11-05T18:24:00-05:00",
        "launch_site": {
          "site_name_long": "Cape Canaveral Air Force Station Space Launch Complex 40"
        },
        "rocket": {
          "rocket_name": "Falcon 9",
          "first_stage": {
            "cores": [
              {
                "flight": 1,
                "core": {
                  "reuse_count": 0,
                  "status": null
                }
              }
            ]
          }
        }
      },
      {
        "mission_name": "Starlink-14 (v1.0)",
        "launch_date_local": "2020-10-24T11:31:00-04:00",
        "launch_site": {
          "site_name_long": "Cape Canaveral Air Force Station Space Launch Complex 40"
        },
        "rocket": {
          "rocket_name": "Falcon 9",
          "first_stage": {
            "cores": [
              {
                "flight": 3,
                "core": {
                  "reuse_count": 2,
                  "status": "unknown"
                }
              }
            ]
          }
        }
      },
      {
        "mission_name": "Starlink-13 (v1.0)",
        "launch_date_local": "2020-10-18T08:25:00-04:00",
        "launch_site": {
          "site_name_long": "Kennedy Space Center Historic Launch Complex 39A"
        },
        "rocket": {
          "rocket_name": "Falcon 9",
          "first_stage": {
            "cores": [
              {
                "flight": 6,
                "core": {
                  "reuse_count": 5,
                  "status": "active"
                }
              }
            ]
          }
        }
      }
    ]
  }
}

Awesome. We just made our first GraphQL query together.

Let’s make our first mutation.

Mutations are how we edit or add data to the database. Below is a mutation that adds my name, rocket, and Twitter to the SpaceX API database. The returning field is us telling the server to send back the name, id, and rocket.

mutation {
  insert_users(objects: {name: "Ethan", rocket: "My SpaceShip", twitter: "ethansbenjamin"}) {
    affected_rows
    returning {
      name
      id
      rocket
    }
  }
}

Here is our payload.

{
  "data": {
    "insert_users": {
      "affected_rows": 1,
      "returning": [
        {
          "name": "Ethan",
          "id": "f6d6d663-8fc4-4532-b042-aac3060afb7f",
          "rocket": "My SpaceShip"
        }
      ]
    }
  }
}

This rocket name is lame. Let’s update it to something cooler. We can use another mutation to update a user in the database.

mutation {
  update_users(where: {id: {_eq: "f6d6d663-8fc4-4532-b042-aac3060afb7f"}}, _set: {rocket: "My Cooler SpaceShip"}) {
    returning {
      rocket
      name
      id
    }
  }
}

In this mutation, we are using the set field to edit the data in the database. We are again, returning the rocket, name, and id.

{
  "data": {
    "update_users": {
      "returning": [
        {
          "rocket": "My Cooler SpaceShip",
          "name": "Ethan",
          "id": "f6d6d663-8fc4-4532-b042-aac3060afb7f"
        }
      ]
    }
  }
}

Awesome, we just made our first mutations. Try sending a rocket and your name to the SpaceX API.

Benefits Over REST APIs:

• Self Documenting: GraphQL APIs use a Schema, which defines the models and queries that can be made. There are many tools available to generate, visualize, and explore GraphQL queries.
• One Endpoint, many use cases.
• Prevents multiple API calls: with a REST API, there may be a need to grab data from multiple endpoints.
• Development speed: instead of going back and forth with backend teams, it is easy to modify the data returned.

GraphQL is an amazing way to create an API. I’m sure working with REST APIs, you understand what limitations and shortcomings you want to avoid. Consider how GraphQL can overcome them :)

This was written for my COMP2406 class. Made with love by Ethan Benjamin :)