GraphQL

Queries

Basic query

{ status }

↓

{ status: 'available' }

Nesting

{ hero { name height } }

↓

{ hero:
    { name: "Luke Skywalker",
      height: 1.74 } }

Lists

{ friends { name } }

↓

{ friends:
    [ { name: "Luke Skywalker" },
      { name: "Han Solo" },
      { name: "R2D2" } ] }

GraphQL queries look the same for both single items or lists of items.

Lookups

{
  hero(id: "1000") { id name }
}

↓

{ hero:
    { id: "1000",
    { name: "Luke Skywalker" } }

Aliases

{
  luke: hero(id: "1000") { name }
  han: hero(id: "1001") { name }
}

↓

{ luke:
    { name: "Luke Skywalker" },
    han:
    { name: "Han Solo" } }

Operation names and variables

Query

query FindHero($id: String!) {
  hero(id: $id) { name }
}

Just to make things less ambiguous. Also, to use variables, you need an operation name.

Variables

{ id: '1000' }

Mutations

Query

{ createReview($review) { id } }

Variables

{ review: { stars: 5 } }

↓

{ createReview: { id: 5291 } }

Mutations are just fields that do something when queried.

Multiple types

{
  search(q: "john") {
    id
    ... on User { name }
    ... on Comment { body author { name } }
  }
}

Great for searching.

Over HTTP

GET

fetch('http://myapi/graphql?query={ me { name } }')

POST

fetch('http://myapi/graphql', {
  body: JSON.stringify({
    query: '...',
    operationName: '...',
    variables: { ... }
  })
})

Schema

Basic schemas

type Query {
  me: User
  users(limit: Int): [User]
}

type User {
  id: ID!
  name: String
}

See: sogko/graphql-shorthand-notation-cheat-sheet

Built in types

Scalar types

Type definitions

Type modifiers

Mutations

type Mutation {
  users(params: ListUsersInput) [User]!
}

Interfaces

interface Entity {
  id: ID!
}

type User implements Entity {
  id: ID!
  name: String
}

Enums

enum DIRECTION {
  LEFT
  RIGHT
}

type Root {
  direction: DIRECTION!
}

Unions

type Artist { ··· }
type Album { ··· }

union Result = Artist | Album

type Query {
  search(q: String) [Result]
}

References

Essential quotes

"GraphQL is about asking for specific fields on objects"
"The query has exactly the same shape as the result"
"Clients can fetch lots of related data in one request, instead of making several roundtrips in a classic REST architecture"
"GraphQL queries look the same for both single items or lists of items"
"In REST, you can only pass a single set of arguments but in GraphQL, every field and nested object can get its own set of arguments, making GraphQL a complete replacement for making multiple API fetches"
"While query fields are executed in parallel, mutation fields run in series, one after the other"

Glossary

Type
Field
Function for each field on each type

type Query {
  me: User
}

type User {
  id: ID
  name: String
}

function Query_me(request) {
  return request.auth.user;
}

function User_name(user) {
  return user.getName();
}

Steps involved

Receive GraphQL query
Validate query against the types and field that are defined
Run provided functions to produce the result

Example Query

{
  me {
    name
  }
}

JSON result

{
  "me": {
    "name": "Luke Skywalker"
  }
}

Example Query

{
  hero {
    name
  }
}

JSON result

{
  "data": {
    "hero": {
      "name": "R2-D2"
    }
  }
}

Nested data with arrays

Query

{
  hero {
    name
    # Queries can have comments!
    friends {
      name
    }
  }
}

JSON result

{
  "data": {
    "hero": {
      "name": "R2-D2",
      "friends": [
        {
          "name": "Luke Skywalker"
        },
        {
          "name": "Han Solo"
        },
        {
          "name": "Leia Organa"
        }
      ]
    }
  }
}

Pass arguments to fields

Query

{
  human(id: "1000") {
    name
    height
  }
}

JSON result

{
  "data": {
    "human": {
      "name": "Luke Skywalker",
      "height": 1.72
    }
  }
}

Pass arguments into scalar fields to let the server transform it

Query

{
  human(id: "1000") {
    name
    height(unit: FOOT) # Enumeration type
  }
}

JSON result

{
  "data": {
    "human": {
      "name": "Luke Skywalker",
      "height": 5.6430448
    }
  }
}

Data types for arguments

Enumeration type
GraphQL's default set of types
The GraphQL server can declare its own custom types (must be serializable)

Aliases to query the same field with different arguments

Aliases let you rename the result of a field to anything you want

{
  empireHero: hero(episode: EMPIRE) {
    name
  }
  jediHero: hero(episode: JEDI) {
    name
  }
}

JSON result

{
  "data": {
    "empireHero": {
      "name": "Luke Skywalker"
    },
    "jediHero": {
      "name": "R2-D2"
    }
  }
}

Fragments to split queries into reusable units

{
  leftComparison: hero(episode: EMPIRE) {
    ...comparisonFields
  }
  rightComparison: hero(episode: JEDI) {
    ...comparisonFields
  }
}

fragment comparisonFields on Character {
  name
  appearsIn
  friends {
    name
  }
}

JSON result

{
  "data": {
    "leftComparison": {
      "name": "Luke Skywalker",
      "appearsIn": [
        "NEWHOPE",
        "EMPIRE",
        "JEDI"
      ],
      "friends": [
        {
          "name": "Han Solo"
        },
        {
          "name": "Leia Organa"
        },
        {
          "name": "C-3PO"
        },
        {
          "name": "R2-D2"
        }
      ]
    },
    "rightComparison": {
      "name": "R2-D2",
      "appearsIn": [
        "NEWHOPE",
        "EMPIRE",
        "JEDI"
      ],
      "friends": [
        {
          "name": "Luke Skywalker"
        },
        {
          "name": "Han Solo"
        },
        {
          "name": "Leia Organa"
        }
      ]
    }
  }
}

Use variables in fragments

query HeroComparison($first: Int = 3) {
  leftComparison: hero(episode: EMPIRE) {
    ...comparisonFields
  }
  rightComparison: hero(episode: JEDI) {
    ...comparisonFields
  }
}

fragment comparisonFields on Character {
  name
  friendsConnection(first: $first) {
    totalCount
    edges {
      node {
        name
      }
    }
  }
}

Variable

{"first": 2}

JSON result

{
  "data": {
    "leftComparison": {
      "name": "Luke Skywalker",
      "friendsConnection": {
        "totalCount": 4,
        "edges": [
          {
            "node": {
              "name": "Han Solo"
            }
          },
          {
            "node": {
              "name": "Leia Organa"
            }
          }
        ]
      }
    },
    "rightComparison": {
      "name": "R2-D2",
      "friendsConnection": {
        "totalCount": 3,
        "edges": [
          {
            "node": {
              "name": "Luke Skywalker"
            }
          },
          {
            "node": {
              "name": "Han Solo"
            }
          }
        ]
      }
    }
  }
}

Operation types

query (can be omitted with "query shorthand syntax" -> no name + no variable definitions)
mutation
subscription

Operation name

Is only required in multi-operation documents
"Name your queries to make the code less ambigous"

query HeroNameAndFriends {
  hero {
    name
    friends {
      name
    }
  }
}

Using variables

It's not needed to manipulate the query string at runtime
Never do string interpolation to construct queries from user-supplied values

Steps for using variables

Replace the static value with $variableName
Declare $variableName as an accepted variable
Pass variableName: value (usually) as JSON

Query with variable definition

query HeroNameAndFriends($episode: Episode) {
  hero(episode: $episode) {
    name
    friends {
      name
    }
  }
}

Variable

{
  "episode": "JEDI"
}

JSON result

{
  "data": {
    "hero": {
      "name": "R2-D2",
      "friends": [
        {
          "name": "Luke Skywalker"
        },
        {
          "name": "Han Solo"
        },
        {
          "name": "Leia Organa"
        }
      ]
    }
  }
}

Variable definitions

Like arguments to a query
Must be prefixed with a $ sign followed by their type ($episode: Episode)

Required variable definitions

are suffixed with a ! sign ($episode: Episode!)

Default variable values

are suffixed with " sign ($episode: Episode = JEDI)

query HeroNameAndFriends($episode: Episode = JEDI) {
  hero(episode: $episode) {
    name
    friends {
      name
    }
  }
}

Directives to dynamically change the structure using variables

Example: UI component that has a summarized and a detailed view
Directives can be attached to a filed or fragment incusion
Two directives built into the spec:
- include(if: Boolean) - Includes this field only if the argument is true
- skip(if: Boolean) - Skips this field if the argument is true

query Hero($episode: Episode, $withFriends: Boolean!) {
  hero(episode: $episode) {
    name
    friends @include(if: $withFriends) {
      name
    }
  }
}

Summarized view

Variables

{
  "episode": "JEDI",
  "withFriends": false
}

JSON result

{
  "data": {
    "hero": {
      "name": "R2-D2"
    }
  }
}

Detailed view

Variables

{
  "episode": "JEDI",
  "withFriends": true
}

JSON result

{
  "data": {
    "hero": {
      "name": "R2-D2",
      "friends": [
        {
          "name": "Luke Skywalker"
        },
        {
          "name": "Han Solo"
        },
        {
          "name": "Leia Organa"
        }
      ]
    }
  }
}

Mutations

We can mutate and query the new value of a field with one request
createReview field returns the stars and commentary fields of the newly created review
The review variable is not a scalar - It's an input object type

mutation CreateReviewForEpisode($ep: Episode!, $review: ReviewInput!) {
  createReview(episode: $ep, review: $review) {
    stars
    commentary
  }
}

Variables

{
  "ep": "JEDI",
  "review": {
    "stars": 5,
    "commentary": "This is a great movie!"
  }
}

JSON result

{
  "data": {
    "createReview": {
      "stars": 5,
      "commentary": "This is a great movie!"
    }
  }
}

Multiple fields in mutations

While query fields are executed in parallel, mutation fields run in series, one after the other
2 incrementCredits mutations in one request mean: the first is guaranteed to finish before the second begins

Inline Fragments for fields that return an interface or a union type

The hero field returns the type Character, which might be either a Human or a Droid depending on the episode argument
name exists on both so you can directly ask for that in the query
To ask for a field on the concrete type, you need to use an inline fragment with a type condition

query HeroForEpisode($ep: Episode!) {
  hero(episode: $ep) {
    name
    ... on Droid {
      primaryFunction
    }
    ... on Human {
      height
    }
  }
}

Variables

{
  "ep": "JEDI"
}

JSON result

{
  "data": {
    "hero": {
      "name": "R2-D2",
      "primaryFunction": "Astromech"
    }
  }
}

Queries​

Basic query​

↓

Nesting​

↓​

Lists​

↓​

Lookups​

↓​

Aliases​

↓​

Operation names and variables​

Query​

Variables​

Mutations​

Query​

Variables​

↓​

Multiple types​

Over HTTP​

GET​

POST​

Schema​

Basic schemas​

Built in types​

Scalar types​

Type definitions​

Type modifiers​

Mutations​

Interfaces​

Enums​

Unions​

References​

Essential quotes

Glossary

Steps involved

Nested data with arrays

Pass arguments to fields

Pass arguments into scalar fields to let the server transform it

Data types for arguments

Aliases to query the same field with different arguments

Fragments to split queries into reusable units

Use variables in fragments

Operation types

Operation name

Using variables

Variable definitions

Required variable definitions

Default variable values

Directives to dynamically change the structure using variables

Mutations

Multiple fields in mutations

Inline Fragments for fields that return an interface or a union type

Queries

Basic query

Nesting

↓

Lists

↓

Lookups

↓

Aliases

↓

Operation names and variables

Query

Variables

Mutations

Query

Variables

↓

Multiple types

Over HTTP

GET

POST

Schema

Basic schemas

Built in types

Scalar types

Type definitions

Type modifiers

Mutations

Interfaces

Enums

Unions

References