Hermes Wiki
Developer/CommunicationPatterns/Protocols/GraphQL/CaseStudies/github-rest-v3-vs-graphql-v4-measuring-the-savings

GitHub API: Measuring What GraphQL Actually Saved Over REST

Problem + constraints

GitHub is one of the few large-scale APIs that has run REST (v3) and GraphQL (v4) side by side for years, giving researchers a rare chance to measure GraphQL's claimed benefits against a real, heavily-used API rather than a synthetic benchmark. GitHub's REST v3 API is resource-oriented in the classic sense: a request for a repository returns a fixed, large JSON object with every field the API designers decided a "repository" should include, whether or not the caller needs most of them, and a client that wants related data (say, a repository's owner and its recent issues) has to make additional round trips, one per resource. That's the textbook over-fetching and N+1-request problem REST APIs accumulate as their resource graphs grow richer over time — and it was exactly the problem GitHub's GraphQL v4 API was built to address, by letting a client specify precisely the fields and relationships it wants in a single request.

An empirical study by researchers Gleison Brito and Marco Tulio Valente ("Migrating to GraphQL: A Practical Assessment," analyzing real open-source client applications and API traffic) put actual numbers on the gap that had mostly been argued about qualitatively. Measuring responses from GitHub's own dual APIs, they found the REST v3 API returned a median of 93.5 fields per response object, against a median of 5.5 fields for equivalent GraphQL v4 queries — a roughly 94% reduction in fields the client received but didn't ask for. On a separate comparison retrieving information about a batch of repositories, REST required 40 separate requests transferring about 93KB, while the equivalent GraphQL query completed in 2 requests transferring about 6.1KB. In a related measurement of raw payload size for a broader dataset pull, the gap widened further: roughly 9.8MB via REST against roughly 86KB via GraphQL for comparable data.

Solution

GitHub's GraphQL v4 API is the solution these numbers describe: a single schema exposing the same underlying data as v3, but queried by field-level selection instead of fixed resource shapes, and capable of resolving related entities (owner, issues, pull requests, reviewers) in one round trip via nested query structure instead of one REST call per relationship. The study's core finding is that this design choice pays off precisely where REST struggles most — deeply nested, relationship-heavy reads where the client only needs a subset of each resource's fields — and the savings compound with the size and connectedness of what's being fetched, which is why the batch-repository comparison shows a bigger relative gap than a single flat resource would.

The study is equally clear about what GraphQL didn't fix for free: migrating an existing REST-based client isn't a drop-in replacement. Client codebases built against REST tend to be organized around many small functions, each consuming one small, predictable REST response; GraphQL's value comes from consolidating what used to be many small requests into fewer, larger, more expressive ones, which means the client-side code has to be restructured around composing queries rather than composing sequential REST calls. The researchers characterized this refactoring as a genuinely non-trivial re-engineering effort, not a mechanical search-and-replace — which is a real cost that has to be weighed against the transfer and request-count savings on the other side of the ledger.

What to steal

  • Over-fetching is measurable, not just a slide-deck talking point. "GraphQL reduces over-fetching" is often stated without evidence in adoption pitches; this study is a rare case where someone actually instrumented a production-scale API and put a number on it (94% fewer fields returned than requested, on a widely used real API). When making the case for or against a GraphQL migration, prefer measuring your own API's actual over-fetch ratio over asserting the general claim.
  • The savings scale with relationship depth, not flat resource size. The gap between REST and GraphQL widened specifically on the batch/nested-data comparison, not the single-resource one. That's the signal for where GraphQL earns its complexity in your own system: a read-heavy page that stitches together several related resources (a storefront view combining a product, its reviews, and its seller, for example) is where the case is strongest — a single flat CRUD resource has much less to gain.
  • Client-side migration cost is real and should be budgeted as its own line item, not assumed away. The study found that REST clients built around small, single-purpose functions don't refactor cleanly into consolidated graph queries. Treat a REST-to-GraphQL migration as a client architecture project, not a backend endpoint swap — the backend schema is often the easier half of the work.
  • Dual-running both APIs, as GitHub did, is itself a valid strategy. GitHub didn't force a hard cutover; v3 and v4 have coexisted for years, letting clients migrate at their own pace and letting exactly this kind of comparative measurement exist in the first place. A phased, dual-API rollout reduces migration risk and gives you the same before/after data GitHub's case made possible, applied to your own traffic.

Engineering Lens

This is one of the few places the REST-vs-GraphQL debate moves from architectural preference to measured evidence, because GitHub's API surface is large, real, and genuinely used by both API styles simultaneously rather than one being a paper migration. The concrete numbers matter less as universal constants (a 94% field reduction is specific to GitHub's schema shape and query patterns) than as a demonstration of the mechanism: over-fetching cost scales with how much a resource's full representation exceeds what any given client actually needs, and that gap grows, not shrinks, as an API's resources accumulate more optional fields and relationships over its lifetime — which is exactly the trajectory most mature REST APIs are on. The honest counterweight the same study supplies is the migration-cost finding: a real GraphQL adoption decision isn't "GraphQL is more efficient," it's "is the over-fetching cost on our actual nested-read traffic large enough to justify the client refactor," and that's a question worth measuring on your own API rather than assuming from GitHub's numbers.

Sources

Hermes Wiki