Understanding GitHub's GraphQL API

Why GitHub Uses GraphQL #

GitHub chose GraphQL for their v4 API because their data model is a deeply interconnected graph. A User owns Repositories, which have Issues, which have Comments, which have Reactions, which are made by Users — it is all connected. REST forced GitHub into creating hundreds of endpoints that returned either too much or too little data. GraphQL lets clients traverse these relationships naturally.

The Endpoint and Authentication #

GitHub's GraphQL API lives at a single URL:

https://api.github.com/graphql

Authentication is mandatory. Unlike GitHub's REST API which allows limited unauthenticated access, the GraphQL API requires a valid token for every single request. You authenticate by including a Bearer token in the Authorization header.

Key Types in the Schema #

GitHub's GraphQL schema is enormous — thousands of types and fields. Here are the ones we will use in this tutorial:

Type	What It Represents	Key Fields
User	A GitHub user account	login, name, bio, avatarUrl, repositories
Repository	A Git repository	name, description, stargazerCount, url, issues
Issue	A repository issue	title, body, state, author, createdAt
PullRequest	A pull request	title, state, merged, additions, deletions
Starrable	Anything that can be starred	stargazerCount, viewerHasStarred

The viewer Field #

One of the most useful root fields in GitHub's schema is viewer. This always returns the currently authenticated user — the person whose token you are using. It is perfect for building profile screens:

query {
  viewer {
    login
    name
    bio
    avatarUrl
    followers { totalCount }
    following { totalCount }
    repositories { totalCount }
  }
}

Connections, Edges, and Nodes #

GitHub uses the Relay-style connection pattern for pagination. Instead of returning a simple array, paginated fields return a Connection object with edges and nodes:

query {
  viewer {
    repositories(first: 10, after: "cursor123") {
      totalCount           # Total number of items
      pageInfo {
        hasNextPage        # Are there more pages?
        endCursor          # Cursor to pass for next page
      }
      edges {
        cursor             # This edge's position
        node {             # The actual repository object
          name
          stargazerCount
        }
      }
      nodes {              # Shortcut: just the objects (no cursors)
        name
        stargazerCount
      }
    }
  }
}

You can use either edges (which gives you per-item cursors) or nodes (a simpler shortcut). For most cases, nodes is sufficient.

Rate Limiting #

GitHub's GraphQL API uses a point-based rate limit, not a simple request count. Each query consumes a certain number of "points" based on its complexity. You get 5,000 points per hour with a personal access token. You can check your remaining balance:

query {
  rateLimit {
    limit
    cost
    remaining
    resetAt
  }
}

---

Creating a GitHub Personal Access Token #

Before we write any code, we need a token to authenticate with GitHub's API.

Why a Personal Access Token? #

GitHub supports several authentication methods: Personal Access Tokens (PAT), GitHub Apps, and OAuth Apps. For learning and personal projects, a PAT is the simplest — it is a string you generate once and include in your API requests.

Step-by-Step: Generate a Fine-Grained Token #

1. Log in to GitHub at github.com
2. Click your profile picture (top right) → Settings
3. In the left sidebar, scroll down and click Developer settings
4. Click Personal access tokens → Fine-grained tokens
5. Click Generate new token
6. Fill in the details:
   • Token name: iOS GraphQL Tutorial
   • Expiration: 30 days (or custom — choose what works for you)
   • Resource owner: Your account
   • Repository access: Select "All repositories" (or specific repos if you prefer)
7. Under Permissions, expand "Repository permissions" and set:
   • Issues: Read and write (for creating issues later)
   • Metadata: Read-only (always required)
   • Starring: Read and write (for starring repos later)
8. Click Generate token
9. Copy the token immediately — you will not be able to see it again!

⚠️ Security Warning: Treat this token like a password. Never commit it to Git, never hardcode it in source code, and never share it. We will discuss secure storage in Chapter 23.

Alternative: Classic Token #

If you prefer a classic token (simpler but less granular):

1. Go to Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click Generate new token (classic)
3. Select scopes: repo, read:user, user:email
4. Generate and copy the token

Test Your Token #

Open Terminal and run this curl command (replace YOUR_TOKEN):

curl -H "Authorization: bearer YOUR_TOKEN" \
     -X POST \
     -d '{"query": "query { viewer { login } }"}' \
     https://api.github.com/graphql

You should see a JSON response with your GitHub username. If you get an authentication error, double-check your token and its permissions.

---