Master GraphQL: From Basics to Real-World Queries and Mutations

GraphQL is an open‑source query language and runtime originally developed by Facebook. It lets a client request exactly the fields it needs, combine multiple resources in a single request, and provides an introspection system for client‑side tooling.

Core Concepts

Operations – GraphQL services expose query (read‑only) and mutation (write) operations. A query is analogous to a REST GET, while mutation corresponds to POST/PUT/DELETE‑type actions.

Types – The schema defines object types. Example:

type User {
  id: ID
  name: String
}

type Query {
  user(login: String!): User
}

The User type lists its fields; the Query type provides entry points such as user.

Scalar types – Built‑in scalars are Int, Float, String, Boolean, and ID. Custom scalars (e.g., Date) can be added. Fields must resolve to scalars or to objects composed of scalars.

Returning a non‑scalar field directly causes an error:

query {
  user   // error: "user" is not a scalar type
}

The correct query selects scalar sub‑fields:

query {
  user {
    id
    name
  }
}

Getting Started with the GitHub GraphQL API

The GitHub GraphQL Explorer (https://developer.github.com/v4/explorer/) provides the GraphiQL interface for writing, validating, and executing queries.

Root types in the schema are Query and Mutation. Expanding Query reveals fields such as user(login: String!): User. A simple query to fetch a user's bio:

{
  user(login: "booxood") {
    bio
  }
}

Execution returns JSON:

{
  "data": {
    "user": {
      "bio": "Happy coding & Happy life"
    }
  }
}

Example: Fetching Issue Comments and Reactions

The following query retrieves the last 10 comments on issue #1 of the gitalk/gitalk repository, together with author information and reaction counts for the HEART emoji.

query {
  repository(owner: "gitalk", name: "gitalk") {
    issue(number: 1) {
      comments(last: 10) {
        totalCount
        nodes {
          author {
            login
            avatarUrl
          }
          body
          reactions(first: 100, content: HEART) {
            totalCount
            viewerHasReacted
          }
        }
      }
    }
  }
}

Mutations for Adding or Removing Reactions

Reactions are modified via mutations on the Mutation root type.

mutation {
  addReaction(input: {subjectId: "MDEyOklzc3VlQ29tbWVudDMxNTQxOTc2NQ==", content: HEART}) {
    reaction {
      content
    }
  }
}

mutation {
  removeReaction(input: {subjectId: "MDEyOklzc3VlQ29tbWVudDMxNTQxOTc2NQ==", content: HEART}) {
    reaction {
      content
    }
  }
}

Key Takeaways

Define a schema with object and scalar types.

Use query to read data and mutation to modify data.

All fields must resolve to scalars or nested object types.

GraphiQL (or any GraphQL client) can explore the schema, compose queries, and execute them against an endpoint such as the GitHub GraphQL API.