GraphQL Tutorial: Complete Step-by-Step Guide

This comprehensive GraphQL tutorial will take you from complete beginner to confident GraphQL developer. We'll cover everything from basic queries to advanced patterns, with plenty of hands-on examples you can try immediately.

By the end of this tutorial, you'll understand how to read and write GraphQL queries, design schemas, handle mutations, and implement best practices. Use our GraphQL formatter to practice formatting queries as you learn, and our schema validator to check your schemas.

What You'll Need

Chapter 1: Understanding the Basics

What Makes GraphQL Different?

GraphQL is a query language that lets clients ask for exactly the data they need. Unlike REST where you get fixed responses, GraphQL gives you complete control over the data structure.

type Book {
  id: ID!
  title: String!
  author: Author!
  publishedYear: Int
}

type Author {
  id: ID!
  name: String!
  books: [Book!]!
}

type Query {
  book(id: ID!): Book
  books: [Book!]!
  author(id: ID!): Author
}

Chapter 2: Your First Query

Let's write a simple query to fetch book data:

query {
  book(id: "1") {
    title
    author {
      name
    }
  }
}

{
  "data": {
    "book": {
      "title": "The Great Gatsby",
      "author": {
        "name": "F. Scott Fitzgerald"
      }
    }
  }
}

Query Fields

You can request as many or as few fields as you need:

query {
  books {
    id
    title
    publishedYear
    author {
      name
      books {
        title
      }
    }
  }
}

Chapter 3: Query Variables

Instead of hardcoding values, use variables to make queries reusable:

query GetBook($bookId: ID!) {
  book(id: $bookId) {
    title
    author {
      name
    }
  }
}

{
  "bookId": "1"
}

Variables are defined with $ and their type. The ! makes them required.

Chapter 4: Mutations (Creating & Updating Data)

Mutations are how you modify data in GraphQL. Think of them as POST, PUT, DELETE in REST.

Schema Definition

type Mutation {
  createBook(title: String!, authorId: ID!): Book!
  updateBook(id: ID!, title: String): Book!
  deleteBook(id: ID!): Boolean!
}

Creating a Book

mutation {
  createBook(
    title: "New GraphQL Book"
    authorId: "123"
  ) {
    id
    title
    author {
      name
    }
  }
}

Chapter 5: Advanced Query Techniques

Aliases

Query the same field multiple times with different arguments:

query {
  book2020: books(year: 2020) {
    title
  }
  book2021: books(year: 2021) {
    title
  }
}

Fragments (DRY Queries)

Reuse common field selections:

fragment BookDetails on Book {
  id
  title
  publishedYear
  author {
    name
  }
}

query {
  book(id: "1") {
    ...BookDetails
  }
  books {
    ...BookDetails
  }
}

Chapter 6: Building a Real API

Let's build a simple GraphQL server with Node.js and Apollo Server:

Step 1: Install Dependencies

npm install apollo-server graphql

Step 2: Define Your Schema

const { ApolloServer, gql } = require('apollo-server');

const typeDefs = gql`
  type Book {
    id: ID!
    title: String!
    author: String!
  }

  type Query {
    books: [Book!]!
    book(id: ID!): Book
  }

  type Mutation {
    addBook(title: String!, author: String!): Book!
  }
`;

Step 3: Create Resolvers

const books = [
  { id: '1', title: '1984', author: 'George Orwell' },
  { id: '2', title: 'Brave New World', author: 'Aldous Huxley' }
];

const resolvers = {
  Query: {
    books: () => books,
    book: (parent, { id }) => books.find(book => book.id === id)
  },
  Mutation: {
    addBook: (parent, { title, author }) => {
      const book = {
        id: String(books.length + 1),
        title,
        author
      };
      books.push(book);
      return book;
    }
  }
};

Step 4: Start the Server

const server = new ApolloServer({ typeDefs, resolvers });

server.listen().then(({ url }) => {
  console.log(`Server ready at ${url}`);
});

Visit http://localhost:4000 and you'll see Apollo's GraphQL Playground! Try our JSON to GraphQL converter to quickly generate schemas from sample data.

GraphQL Best Practices

Common Mistakes to Avoid

Essential GraphQL Tools

Next Steps

Related Articles

External Resources & Further Learning