Why GitHub Switched to GraphQL: Benefits Over REST APIs

Background

GitHub announced a public API built with GraphQL.

GitHub's REST API is already mature and widely referenced; many tutorials exist.

GraphQL is a query language specification created by Facebook in 2012, open‑sourced in 2015, and now used internally to replace REST.

GitHub explains why it chose GraphQL.

What problems does the REST API have?

The main issue is scalability; as APIs evolve they become bloated.

In a typical REST design the server defines endpoints and the client calls the ones it needs, then combines the results.

For example, an early user endpoint might return only id and name. Later it adds many fields such as age, city, etc. Clients that only need name or headimage must still receive the full payload and filter it themselves, increasing network traffic.

Complex use‑cases often require calling several independent endpoints (e.g., article, comments, author) to assemble enough data, which is inflexible.

GitHub also faced other REST limitations, such as ensuring type‑safe client parameters, generating documentation from code, and identifying OAuth scopes for each endpoint.

What are the advantages of using GraphQL?

In GraphQL the client decides which fields to fetch.

With REST the server decides the shape of the response; the client can only pick from it, possibly needing multiple requests.

In GraphQL the client tells the server exactly what data it wants, and the server returns precisely that.

Example query to fetch a few user attributes:

{
  viewer {
    login
    bio
    location
    isBountyHunter
  }
}

Corresponding response:

{
  "data": {
    "viewer": {
      "login": "octocat",
      "bio": "I've been around the world, from London to the Bay.",
      "location": "San Francisco, CA",
      "isBountyHunter": true
    }
  }
}

The response keys match the request exactly.

A more complex query can retrieve starred repository counts, the first three repositories with their star, fork, watcher, and open‑issue totals in a single request:

{
  viewer {
    login
    starredRepositories {
      totalCount
    }
    repositories(first: 3) {
      edges {
        node {
          name
          stargazers { totalCount }
          forks { totalCount }
          watchers { totalCount }
          issues(states:[OPEN]) { totalCount }
        }
      }
    }
  }
}

Response (truncated for brevity):

{
  "data": {
    "viewer": {
      "login": "octocat",
      "starredRepositories": { "totalCount": 131 },
      "repositories": {
        "edges": [
          { "node": { "name":"octokit.rb", "stargazers":{"totalCount":17}, "forks":{"totalCount":3}, "watchers":{"totalCount":3}, "issues":{"totalCount":1} } },
          { "node": { "name":"octokit.objc", "stargazers":{"totalCount":2}, "forks":{"totalCount":0}, "watchers":{"totalCount":1}, "issues":{"totalCount":10} } },
          { "node": { "name":"octokit.net", "stargazers":{"totalCount":19}, "forks":{"totalCount":7}, "watchers":{"totalCount":3}, "issues":{"totalCount":4} } }
        ]
      }
    }
  }
}

All required data is obtained with a single request.

Other GraphQL features include batch requests with dependent queries, subscriptions for real‑time updates, and data latency directives to mark parts of the response as time‑insensitive.

Conclusion

Beyond GitHub, many large companies such as Pinterest, Coursera, and Shopify have adopted GraphQL.

GitHub is committed to improving its GraphQL API, making it more flexible and robust.