Before comparing REST and GraphQL, it helps to be completely clear on what an API is doing in the first place, and why a platform as large as GitHub would maintain two separate ways of doing the same basic job.

An API (Application Programming Interface) is a defined way for one piece of software to ask another piece of software for data or to trigger an action, without needing to know how that other software works internally. When you use a tool that shows your GitHub pull requests inside your code editor, or a bot that automatically labels new issues, that tool is not somehow reading GitHub’s website — it is making structured requests to a GitHub API and receiving structured data back.

GitHub exposes two separate APIs for this purpose:

GitHub did not build GraphQL to replace REST — both are actively maintained, and GitHub’s own official guidance is that the right choice depends on what you are building. Understanding why requires understanding how each one actually works, which is where the next several chapters go.

REST has been GitHub’s primary API since the platform’s early years, and its design directly reflects a style of API architecture called Representational State Transfer, first described in the early 2000s and adopted almost universally across the web since.

In REST, every piece of data GitHub knows about is modeled as a resource, and every resource lives at its own fixed web address, called an endpoint. A specific repository is a resource. The list of issues on that repository is a resource. A single pull request is a resource. Each of these has its own dedicated endpoint address, and asking for that resource means sending a request to that specific address.

flowchart LR
    Client["Client Application"] -->|"GET /repos/owner/repo"| E1["Repository Endpoint"]
    Client -->|"GET /repos/owner/repo/issues"| E2["Issues Endpoint"]
    Client -->|"GET /repos/owner/repo/pulls"| E3["Pull Requests Endpoint"]
    Client -->|"GET /users/username"| E4["User Endpoint"]
    E1 --> R1["Fixed Repository JSON Shape"]
    E2 --> R2["Fixed Issues Array Shape"]
    E3 --> R3["Fixed Pull Requests Array Shape"]
    E4 --> R4["Fixed User JSON Shape"]
    

HTTP Verbs as Actions

REST reuses the standard verbs already built into the web’s own HTTP protocol to describe what action is being taken on a resource: retrieving data, creating something new, updating something existing, or deleting something. This mapping — action expressed through the verb, target expressed through the address — is one of REST’s defining characteristics, and it is why REST endpoints tend to read almost like plain English once you know the pattern: “retrieve the issues on this repository,” “create a new issue on this repository,” “update this specific issue,” “delete this specific comment.”

Fixed Response Shapes

Every REST endpoint has a predetermined response structure designed and documented by GitHub in advance. Requesting a repository’s data always returns the same set of fields — name, description, star count, owner, and dozens more — regardless of whether the calling application actually needs all of them. This predictability is a strength for simple use cases and a weakness for precise ones, a tension that becomes the central theme of this entire guide.

Versioning

Because REST endpoints have a fixed, documented shape, changing that shape in a way that removes or renames a field would break every application depending on the old shape. GitHub manages this by publishing dated API versions, allowing existing integrations to keep working against an older, stable version while new integrations can opt into newer versions with different behavior.

GraphQL takes a fundamentally different starting point: instead of many endpoints each returning a fixed shape, there is exactly one endpoint, and the shape of the response is decided by the caller, every single time.

GraphQL is a query language for APIs, originally developed at a major social media company to solve exactly the kind of over-fetching and under-fetching problems described later in this guide, and GitHub adopted it as an official, fully supported second API surface. Rather than many resource addresses, GraphQL exposes a single endpoint. Every request sent to that endpoint carries a query — a structured description, written in GraphQL’s own syntax, of exactly which pieces of data the caller wants, including how deeply to follow relationships between them.

flowchart LR
    Client["Client Application"] -->|"POST / with a Query
    describing exact fields needed"| Single["Single GraphQL Endpoint"]
    Single --> Schema["GitHub's GraphQL Schema
    (the full graph of available data)"]
    Schema --> Resolve["Resolvers Fetch Only
    the Requested Fields"]
    Resolve --> Response["Response Shaped
    Exactly Like the Query"]
    

The Schema: A Typed Map of Everything Available

GraphQL APIs are built around a schema — a complete, strongly typed description of every kind of data available, every field on every type, and how those types connect to one another. GitHub’s GraphQL schema describes repositories, issues, pull requests, users, organizations, and how each connects to the others, forming something closer to a navigable graph of related data than a list of separate resources — which is where GraphQL gets its name.

Queries: Asking for Exactly What You Need

A GraphQL query mirrors the shape of the data it wants back. If a caller wants only a repository’s name and its five most recent open issues’ titles, the query says exactly that, and GitHub’s response contains exactly that — no star count, no owner details, no extra issue fields the caller never asked for.

Mutations: Making Changes

Where REST uses different HTTP verbs to express different actions, GraphQL uses a single request mechanism for everything, but distinguishes read operations (called queries) from write operations (called mutations) at the language level. A mutation to open a new issue looks structurally similar to a query, but is explicitly named and typed as an action that changes data rather than merely reading it.

To really understand why GitHub built a second API architecture instead of just improving REST, you need to understand the two specific inefficiencies GraphQL was designed to eliminate.

Over-Fetching

Over-fetching happens when a REST endpoint’s fixed response shape includes far more data than the calling application actually needs. A mobile app that only wants to display a repository’s name and star count still receives the repository’s full description, its license details, its default branch name, its homepage URL, and dozens of other fields — all transmitted over the network, parsed, and then immediately discarded, wasting bandwidth and processing time on both ends for no benefit.

Under-Fetching

Under-fetching is the opposite problem: a single REST endpoint often does not include everything a caller needs in one response, forcing the application to make several separate requests to different endpoints and manually stitch the results together. Displaying a repository along with its five most recent contributors’ profile pictures might require one request for the repository, then a separate request per contributor to fetch their avatar — a pattern commonly called the “N+1 requests” problem, because one initial request for a list frequently balloons into N additional requests, one per item in that list.

flowchart TD
    Need["Goal: Repo Name + 5 Contributors' Avatars"] --> R1["REST: Request 1
    GET repository"]
    R1 --> R2["REST: Request 2
    GET contributor 1"]
    R1 --> R3["REST: Request 3
    GET contributor 2"]
    R1 --> R4["REST: Request 4..6
    GET contributors 3-5"]
    Need --> G1["GraphQL: Single Request
    repo name + first 5 contributors' avatars,
    nothing else"]
    

To make the difference concrete without diving into syntax, walk through the same real task — “show a repository’s name, its open issue count, and the usernames of the last three people who commented on its most recent issue” — through both architectures.

Notice what changed: the REST version required three separate network round trips, each returning far more data than needed, with the caller doing the work of stitching the results together. The GraphQL version required one round trip, returning exactly the requested shape, with GitHub’s own servers doing the work of following the relationships internally.

Because REST and GraphQL count “cost” so differently, GitHub also has to rate-limit them differently — and this is one of the most practically important differences for anyone building against these APIs at scale.

REST: Counting Requests

GitHub’s REST API enforces a limit on the raw number of requests an authenticated caller can make within a given time window, regardless of how much or how little data each individual request returns. A request for a tiny piece of data and a request for a massive list of results both count as exactly one request against the same limit.

GraphQL: Counting Query Complexity

Because a single GraphQL query can request an arbitrarily large, deeply nested amount of data — following relationships many layers deep in one call — counting raw requests would be meaningless; a single enormous query could pull far more data than a hundred REST requests combined. GitHub instead assigns every GraphQL query a calculated point cost based on the complexity and depth of what it requests, and limits the total points a caller can spend within a time window, rather than the number of queries itself.

Both APIs sit behind the same underlying identity system, but the way permissions are scoped and checked differs slightly in practice.

Shared Identity Foundation

Both the REST API and the GraphQL API authenticate callers using the same underlying mechanisms available on GitHub — personal access tokens, GitHub App installation tokens, and OAuth tokens issued through an authorized application. A single valid token generally works for both APIs, and the same scoped permissions model governs what either API is allowed to see or change on the caller’s behalf.

Field-Level Access in GraphQL

Because GraphQL queries can request deeply nested, cross-cutting data in a single call, GitHub’s GraphQL layer checks permissions at a finer grain — evaluating whether the caller’s token is allowed to see each individual field being requested, not just whether it can access the top-level resource. A query that spans a public repository and a private one nested inside its data graph will return the public data while quietly omitting or erroring on the private portion the token cannot see.

Resource-Level Access in REST

REST’s access checks map more directly onto each endpoint: a request either has permission to hit that specific endpoint for that specific resource, or it does not, and the entire request succeeds or fails as a unit rather than partially succeeding field by field.

GitHub does not present these as competing replacements for one another — its own documentation frames them as complementary tools suited to different situations.

GitHub Actions and Automation

Many automation scripts and GitHub Actions workflows still lean on the REST API for simple, well-defined operations — labeling an issue, merging a pull request — precisely because those tasks map cleanly onto a single REST endpoint and a single HTTP verb, with no benefit from GraphQL’s flexible shaping.

Dashboards, Analytics, and Data-Heavy Tools

Tools that build rich views across many related GitHub entities at once — project management integrations, analytics dashboards, custom internal tooling that combines organization, repository, and contributor data — tend to gravitate toward GraphQL, because the alternative in REST would mean orchestrating and combining the results of many separate calls by hand.

Any API returning potentially huge lists — every issue ever filed on a large repository, for instance — has to break results into manageable pages, and REST and GraphQL approach this differently as well.

REST: Page Numbers

GitHub’s REST API commonly uses simple page-number-based pagination for list endpoints, where a caller requests a given page of a given size, and moves to the next page by incrementing a page number parameter on subsequent requests.

GraphQL: Cursor-Based Pagination

GitHub’s GraphQL API uses a more robust pattern called cursor-based pagination, where each page of results comes with an opaque “cursor” marker pointing to exactly where that page ended, and the next request simply says “give me the next page after this cursor.” This approach is more resilient to items being added or removed from a list while paging through it, since it tracks position relative to a specific item rather than a raw page number that can shift if the underlying list changes mid-traversal.

How each API reports that something went wrong is another meaningful divergence, and it affects how integration code has to be written.

REST: HTTP Status Codes

REST leans heavily on standard HTTP status codes to communicate outcomes — a successful retrieval, a successful creation, a request for something that doesn’t exist, a request the caller isn’t authorized to make, and so on. Calling code can often make high-level decisions just by inspecting the status code, before even looking at the response body.

You may likeWhat Is Sparse Checkout?→

GraphQL: Always 200, Errors in the Body

GraphQL requests almost always return the same successful HTTP status regardless of whether the query itself fully succeeded, because the HTTP request itself did succeed — the GraphQL endpoint received the query and responded. Any problems with the query — a field that doesn’t exist, a permission failure on part of the requested data, a downstream error resolving one branch of the query — are instead reported inside the response body itself, in a dedicated errors section, potentially alongside the successfully resolved parts of the response.

flowchart TD
    ReqR["REST Request"] --> StatusR{"HTTP Status Code"}
    StatusR -->|"Success Range"| BodyR["Response Body = Data"]
    StatusR -->|"Error Range"| ErrR["Response Body = Error Details"]
    ReqG["GraphQL Request"] --> StatusG["HTTP Status: Success"]
    StatusG --> BodyG["Response Body Contains
    BOTH data AND errors sections,
    possibly at the same time"]
    

Caching — storing a previous response so a repeated request doesn’t have to be fully recomputed — behaves very differently across the two architectures, largely as a consequence of how their endpoints are structured.

REST’s Natural Fit with HTTP Caching

Because every REST resource lives at its own fixed, predictable address, and returns a consistent shape, REST responses can be cached using the web’s standard HTTP caching mechanisms almost for free — a cache simply needs to remember “the last response for this exact address,” which works cleanly because the same address always means the same kind of request.

GraphQL’s More Complex Caching Story

Because every GraphQL request goes to the same single endpoint, and the specific data requested varies with every differently written query, the same simple “cache by address” approach does not work. Effective GraphQL caching instead typically happens at a finer grain — caching individual pieces of data by their own unique identity within the response, so that overlapping queries requesting the same underlying entity from different angles can still reuse already-fetched data, a pattern that generally requires more deliberate client-side tooling to implement well.

Teams building against either API tend to fall into a recognizable set of good and bad habits. Naming them makes them easier to catch during design review.

Pattern: Matching the API to the Shape of the Task

Choosing REST for simple, isolated, single-resource operations, and GraphQL for tasks that genuinely need several related pieces of data assembled together — rather than defaulting to one API for everything regardless of the task’s actual shape.

Pattern: Requesting Only What Is Displayed

In GraphQL specifically, writing queries that request exactly the fields a given screen or feature actually renders, and nothing more — resisting the temptation to request broad, “just in case” data that reintroduces the very over-fetching problem GraphQL exists to solve.

Anti-pattern: Treating GraphQL Queries Like REST Endpoints

Writing one enormous, fixed GraphQL query that always requests every field any part of the application might ever need, and reusing it everywhere — which throws away GraphQL’s core advantage and can even reintroduce over-fetching in a new form.

Anti-pattern: Deeply Nested, Unbounded GraphQL Queries

Writing a GraphQL query that follows relationships many layers deep without limiting how many items are requested at each layer — for example, every repository in an organization, each with every one of their pull requests, each with every one of their reviews — which can produce an enormous point cost and a slow, resource-heavy response, sometimes rejected outright for exceeding complexity limits.

A handful of habits separate integrations that scale smoothly from ones that hit rate limits, break on edge cases, or become difficult to maintain.

Common Mistakes

• Assuming GraphQL is unconditionally “better” and migrating simple REST calls to GraphQL for no functional benefit.
• Forgetting that GraphQL’s rate limit is based on query complexity, and being surprised when a single large query consumes far more of the limit than expected.
• Treating REST’s fixed response shape as if it were customizable, and manually filtering unused fields client-side instead of recognizing that GraphQL exists precisely for that need.
• Writing GraphQL queries with unbounded nested lists, leading to unexpectedly expensive or slow responses.

Seeing how established tools and platforms actually choose between the two makes the earlier guidance feel concrete rather than theoretical.