Introduction to GraphQL - aaronpanch/idea-board GitHub Wiki

In this mini write-up. We'll offer a practical overview of GraphQL.

The Playground

The GraphQL playground is a great way to start playing with GraphQL. In it, you can make both queries and mutations just like a client application would.

To start, navigate to http://localhost:3000/playground

The view is roughly split into two panes (there are a couple more we'll cover later).

1. (Left) Your GQL request
2. (Right) The response

Queries

Let's get our first query going. Copy, paste, and run (by pressing the "Play" button) the following query.

query Ping {
  ping
}

You should see the following response on the right:

{
  "data": {
    "ping": "pong"
  }
}

If so, 🎉 and celebrate! Ok, so now let's recap what happened.

1. The query keyword told GraphQL that this is, unsurprisingly, a query. But, it's more than that—because our queries are "graphs", this is the entry point, and actually refers to a type in GQL, the query_type in our repo. So, we're actually asking for "data" and the data we want is of "Query Type".
2. The Ping (note capitalization) is just a name we assign to this query. It's optional.
3. The { ping } is us "asking" for the field ping on the root Query Type.

So how does GQL know to say "pong" in response? Through resolvers.

Navigate to the file app/graphql/idea_board_graphql/query_type.rb

This is the code that defines our root Query Type. Lets unpack this:

1. The field keyword defines a field (that we just requested). We're defining ping as some data a user can request on the root query type.
2. We specify that it will be of data type GraphQL::Types::String (a scalar)
3. We say it will always have data null: false
4. There's a short description for the built-in documentation

So, back to our question: So how does GQL know to say "pong" in response? We said it does so with a resolver. And yes, you guessed it, that method defined (by the same name as the field) is the resolver!

The purpose of a resolver is to tell GraphQL how to "resolve" or get the data needed to "fill in" the field. In this case, we're returning a simple string, but this could be more involved and fetch items from a DB etc.

Mutations

Next, we'll move on to mutations. Return to the playground and open a new tab.

Copy, paste, and run (by pressing the "Play" button) the following mutation.

mutation Ping {
  ping
}

You should see the following response on the right:

{
  "data": {
    "ping": "pong"
  }
}

Not terribly exciting, but some slightly different stuff is going on! Note the use of the mutation keyword! We're now using the mutation root query type!

As you expected it's really similar to queries. Let's modify our mutation a little bit to be more illustrative:

Copy, paste, and run (by pressing the "Play" button) the following mutation.

mutation Ping {
  ping(pong: "Hello World!")
}

You should see the following response on the right:

{
  "data": {
    "ping": "Hello World!"
  }
}

Magic! Actually no—in this case, our mutation allows for an argument (p.s. queries can too!). An argument allows us to accept data to perform our mutation (or query).

Let's get back to code. Navigate to the file app/graphql/idea_board_graphql/mutation_type.rb

Notice:

1. Our field now has an argument keyword! We're accepting a named argument pong which will serve as a response.
2. It needs to be a string (GQL will check this)
3. It has a default value of "pong"
4. Our resolver is equally as simple, there's a parameter with what the user has entered!