Introduction to GraphQL

gql_intro.md

GraphQL 101

Prerequisites

Before starting this lesson, you should have an established understanding of RESTful APIs. Ideally, you have experience writing API endpoints and/or consuming APIs (third-party or your own).

Goals

By the end of this lesson, you'll be able to:

• Differentiate between a RESTful API and GraphQL API
• Use a GraphQL IDE
• Query a GraphQL API

Introduction to GraphQL (10 minutes)

REST vs GQL

Let's think about how we query for data with a RESTful API within our Rails applications. Typically, we have a different endpoint tied to each different queryable object or objects. For example, with an API housing data about pet owners and their cats and dogs, to query all owners, we'd likely make a GET request to /owners. To query all cats, /owners/ID/cats, and for dogs, /owners/ID/dogs.

Pause & consider

Imagine your application had the need to retrieve information about each owner and each of their pets from this API -- how would we structure our request(s)?

---

With a RESTful API, we'd need to query for the owner and each of its pets separately. We can expect this structure of individual endpoints for all of our GET, POST, PUT, and DELETE needs.

With GraphQL, all of our interactions with the API happen through a single GET request to a single endpoint, typically something like myawesomeapi.com/graphql. It is how we structure that request that specifies to the API exactly what we need from it.

Pause & consider

Without knowing much more, what does that start to change about our API thinking?

Could we imagine how moving away from rigid, prescribed endpoints may free us up to be more flexible with how we request and receive data?

---

Now that we know GraphQL offers a bit more flexibility, prepare to be excited: GraphQL gives us the power to query our applications' owners and all their pets all at once ✨.

Let's get into it (20 minutes)

We're going to practice sending queries to the public Countries GraphQL API 🌍.

Launch a GraphQL IDE

We're going to use an IDE (integrated development environment) to give us an interactive visual experience with the API, similar to tools like Postman, but specifically tuned to GraphQL.

1. Head over to https://www.apollographql.com/docs/apollo-server/v2/testing/graphql-playground/ and click "Launch Sandbox"
2. In the top left SANDBOX input, replace localhost:4000 with https://countries.trevorblades.com/graphql
3. Let's "Collapse" the documentation panel on the left for now

Let's take a look at this query:

query Query {
  country(code: "BR") {
    name
    native
    capital
    emoji
    currency
    languages {
      code
      name
    }
  }
}

Pause & consider

What do we think this query is requesting? What do we think the indentation / nesting indicates? (Hint: look at languages)

---

Let's run the query!

We get back our country's information with its related languages data.

Explore

Go ahead and spend a few minutes playing with the query variables and fields you're sending in our original request. Can you cause an error? How does the IDE help you fix your error?

Documentation

When you feel comfortable, let's uncollapse our documentation panel and explore.

Documentation is generated for practically free for us by GraphQL. Thusly, when connected to a GraphQL API within an IDE, fully-traversable documentation for the API you're working with is right at your fingertips.

Explore

Poke around the documentation for the Countries GraphQL API. See what other relational data you can query. Perhaps the names of continents and their countries' names and those countries' states' names!

Going further

Now that you've gotten a sense of what GraphQL is and can do, here are some ways you can further your learning:

• Learn about mutations and input types
• Add the graphql-ruby gem to your Rails project
• Check out the GraphQL Discord Server
• Practice mutations and configuring headers using GitHub's GraphQL API