The Surface-Level Case
GraphQL has been publicly available since 2015, and its position in the API ecosystem remains oddly ambiguous. There are strong third-party advocates — GitHub shipped its fourth API generation as GraphQL in 2016, with Shopify and Yelp following suit — yet a scan of notable providers shows most still default to REST-ish designs. Amazon, Dropbox, Google, Microsoft, Stripe, and Twilio all remain firmly in the resource-and-action-over-HTTP camp. The arguments for strict REST and hypermedia, with their promise of automatic discoverability, have never produced much real-world precedent. But GraphQL's hurdle may be that while it is genuinely better, it is not "better enough" to displace a pattern that is adequate for most purposes.
The often-repeated selling points are valid, but several structural advantages run deeper than the usual pitch. Three core ideas define the surface: explicit field selection, built-in introspection, and a strong type system.
With GraphQL, fields and relationships are requested explicitly — there is no wildcard equivalent to SQL's SELECT *. This trims payload size, particularly valuable on mobile, but more importantly establishes a precise contract between client and server. The type system covers complex objects like User, JSON scalars, enumerations, interfaces, and unions. Nullability is part of the spec, which is a remarkable benefit when building APIs in languages with strict null handling. Where a field might otherwise default to nullable, GraphQL's constraints make response handling more deterministic.
getUser(id: "user_123") {
currency,
email,
subscriptions
}
{
__type(name: "User") {
name
fields {
name
type {
name
}
}
}
}
Every compliant implementation supports introspection — it is required by the GraphQL spec — so client tooling can always rely on it being available. There is no need to retrofit an unstandardized description language like OpenAPI, which is often out of sync with the implementation because it exists separately from the code. GraphQL's documentation is, by construction, tied directly to the running system.
Data as a Traversable Graph
GraphQL's name points to its real conceptual core: it models objects as a graph, rooted at query and mutation nodes that descend into API-specific resources. This is the logical extension of what nearly every REST API already is — a graph that is simply harder to traverse. Resources reference other resources by IDs, and each relation requires a new HTTP round trip.
Stripe's API demonstrates the pain point with its object expansion feature. A user can pass an expand[]=... parameter to replace an ID like cus_123 with its full object, and expansions are chainable — a single request can reveal a dispute's associated charge and that charge's customer. The feature's main payoff is saved API calls, and it is popular enough that Stripe restricts expansions to three levels deep yet routinely receives requests for four.
Discovery Without Extra Tooling
Every API faces the problem of approachability for new users. REST providers typically assemble a custom solution of documentation portals and explorers. GraphQL gets this almost for free with GraphiQL, an in-browser tool for reading documentation and building queries that runs on the standard introspection primitives. It is just an HTML and JavaScript file that can be hosted statically.
Shopify's public GraphiQL installation offers a good demonstration: with the "Docs" panel, a new user can construct a query four or more relations deep without consulting external reference material. A vanilla GraphiQL setup is a more powerful integration tool than what the vast majority of REST providers offer, and it is available automatically with only minor configuration for authentication and CORS. For providers that want a custom experience, modifying the open-source tool to match a specific API's layout is well within reach.
Batching as a First-Class Operation
Any web API that survives long enough will eventually feel pressure to support batch operations. In the REST world, that pressure results in each provider inventing its own bespoke batch specification, straining users who must learn yet another non-standard format. GraphQL includes batching in the specification itself. Multiple operations on a single document can use aliases like userA and userB to disambiguate results in the response, and batch mutations are also supported.
userA: getUser(id: "user_123") {
email
}
userB: getUser(id: "user_456") {
email
}
The availability of this feature does not mean a provider must accept unlimited costly requests. Operations per request can be capped — five is a reasonable default, or even one if that fits a particular threat model. Providers keep control over resource usage while users get a standard mechanism for reducing round trips.
Observability Enables Living APIs
The deepest advantage of GraphQL follows from its explicitness. In REST, an API provider has almost no insight into which fields any given client consumes — every field is assumed to be in use by everyone. That assumption tends to ossify APIs. Removing a field is always a breaking change, so broad and abrupt changes are clustered into major versions released intermittently. A field read model is mostly invisible, and the API changes in big, risky jumps.
GraphQL's explicit contracts are also observable contracts. A provider can log the exact fields requested for every call, giving perfect insight into real usage patterns. That information supports product decisions: a newly introduced field's adoption can be measured immediately; a rarely used field that fits poorly into the design, or is costly to maintain, is flagged as a candidate for retirement. The API evolves in a controlled, gradual way rather than ossifying under uncertainty.
Deprecation becomes a process rather than an event. A field slated for removal is first marked with GraphQL's built-in deprecated annotation, which hides it from interactive documentation. Usage data illuminates which clients still rely on it, and a provider can progressively restrict access to only those users while others are turned away. After a grace period, active outreach can be targeted at remaining users before the field is removed entirely. The API changes because its maintainers can observe and measure the change, allowing versioning to become a gradual evolution toward a better state rather than a sequence of hard breaks.
Consistency Becomes Leverage
GraphQL is not just a collection of clever features; it is a response to real-world API scaling problems that often go unnoticed until they become critical. Its comprehensive specification eliminates much of the ambiguity that plagues ad-hoc designs, which means most GraphQL APIs end up looking remarkably similar. This uniformity is not accidental—it is a deliberate architectural choice that extends across all major implementations.
That enforced consistency pays off in tooling. GraphiQL and other shared utilities work uniformly across any GraphQL service because the underlying conventions are stable. REST, by contrast, offers no such guarantee. Its flexibility has driven its widespread adoption, but that same freedom results in fragmented patterns and bespoke solutions that cannot be easily reused.
The argument is not that REST is broken, but that it is under-designed for the demands of modern clients. Loose conventions leave too much to individual interpretation, and the cost of that divergence accumulates over time. GraphQL’s stricter framework is a trade-off that favors long-term coherence. While there is room for even more opinionated guidance on naming, mutation granularity, and pagination, the current spec already provides a far more sophisticated constraint set than REST can offer.
REST’s momentum is real, but it should not blind us to the advantages of a more disciplined approach. Keeping an eye on the horizon means recognizing that shared convention is not a limitation—it is the foundation for the next generation of API tooling. 1
