REST API vs GraphQL: Two Philosophies of Building APIs

PART I -- REST

1. The History of REST

REST -- Representational State Transfer -- was defined in 2000 by Roy Fielding in his doctoral dissertation at the University of California, Irvine. Fielding wasn't proposing a new technology; he was describing the architectural principles that made the World Wide Web work.

At its core, Fielding observed that the web's success came from a set of constraints: client-server separation, statelessness (each request contains all information needed), a uniform interface (URLs identify resources, HTTP verbs define actions), cacheability, and a layered system where clients can't tell whether they're connected directly to the server or through intermediaries.

These weren't new inventions -- they were formalizations of how HTTP and the web already worked. But naming them created a framework that developers could deliberately design against. By the mid-2000s, as SOAP and XML-RPC were drowning developers in complexity, REST emerged as the simpler, more intuitive alternative.

REST wasn't invented -- it was discovered. Roy Fielding described what was already making the web work, and gave it a name that the industry could rally around.

2. What REST Solved and Promised

To appreciate REST, you need to understand what came before it. In the late 1990s and early 2000s, the dominant approach to web services was SOAP (Simple Object Access Protocol) -- a verbose, XML-based protocol with strict schemas, complex tooling requirements, and WSDL files that described service contracts.

REST promised a radically simpler alternative:

• Simplicity: Use standard HTTP methods (GET, POST, PUT, DELETE) with clean URLs. No WSDL, no envelope wrapping, no XML schema negotiation. A REST API is self-documenting if you follow conventions: GET /users/42 is immediately understandable.
• Statelessness: Each request is self-contained. The server doesn't store client state between requests, making APIs easier to scale horizontally -- any server can handle any request.
• Cacheability: HTTP's built-in caching mechanisms (ETags, Cache-Control headers) work natively with REST. CDNs can cache GET responses without any special configuration, dramatically improving performance for read-heavy APIs.
• Technology agnosticism: REST doesn't mandate a language, framework, or data format. While JSON became the de facto standard, REST APIs can return XML, HTML, or any format the client requests via content negotiation.
• Universal adoption: By leveraging HTTP -- a protocol every device, browser, and programming language already speaks -- REST APIs could be consumed from anywhere, by anything. No special SDK required.

By 2010, REST had effectively won the API architecture war. SOAP retreated to enterprise integration scenarios, and REST became the default choice for building web and mobile APIs. As of late 2024, industry estimates suggest that the vast majority of public APIs follow REST conventions.

3. REST's Shortcomings

REST's simplicity was its strength, but it also created problems that became more painful as applications grew more complex -- especially in the mobile era:

• Over-fetching: A REST endpoint returns a fixed data structure. If you call GET /users/42, you might get the user's name, email, phone, address, preferences, avatar URL, and last login time -- even if you only needed the name. On mobile networks with limited bandwidth, this wasted data adds up.
• Under-fetching (the N+1 problem): Conversely, if you need a user's profile plus their recent posts plus the comments on those posts, you might need three or more sequential API calls: GET /users/42, then GET /users/42/posts, then GET /posts/123/comments. Each round trip adds latency, especially on mobile.
• Endpoint explosion: As applications grow, the number of REST endpoints multiplies. Different clients (web, iOS, Android, smartwatch) often need different data shapes, leading to custom endpoints like /users/42/summary or /users/42/full -- a maintenance burden that scales poorly.
• Versioning headaches: Evolving a REST API without breaking existing clients is notoriously difficult. /api/v1/users vs /api/v2/users creates parallel maintenance paths. Deprecating old versions requires careful client migration coordination.
• Lack of a type system: REST has no built-in schema or type system. API documentation relies on external tools (Swagger/OpenAPI), which can drift from the actual implementation. Clients discover breaking changes at runtime, not at build time.

REST's problems weren't theoretical -- they were felt most painfully by mobile developers at companies like Facebook, where every unnecessary byte and every extra network round trip degraded the user experience for billions of people.

PART II -- GraphQL

4. The Birth of GraphQL

In 2011, Facebook was facing a crisis. Their mobile app was built on HTML5 running inside a WebView -- slow, clunky, and unable to deliver the fluid experience users expected. CEO Mark Zuckerberg would later call betting on HTML5 for mobile "the biggest mistake we made as a company."

The decision was made to rebuild the Facebook iOS app as a fully native application. But the backend APIs were the problem: they returned HTML fragments, not structured data. And the REST endpoints that did exist required multiple round trips to assemble a single News Feed story -- one call for the post, another for the author's profile, another for comments, another for likes.

Three engineers -- Nick Schrock, Dan Schafer, and Lee Byron -- were tasked with solving this. Their insight was radical: instead of the server defining what data each endpoint returns, let the client describe exactly what it needs in a single query, and have the server return precisely that -- nothing more, nothing less.

By August 2012, the rebuilt Facebook iOS app launched, powered internally by this new query language. The results were significant -- the new app was substantially faster, and user engagement reportedly improved considerably. GraphQL stayed an internal Facebook tool for three years, evolving to power nearly all of Facebook's data fetching.

Going Open Source (2015)

In 2015, Facebook decided to open-source React Native's data layer, Relay, which was built on top of GraphQL. To release Relay, they had to release GraphQL itself. So in September 2015, Facebook published the GraphQL specification and a JavaScript reference implementation.

The response was immediate and enthusiastic. Within months, community implementations appeared in Python, Ruby, Java, Go, .NET, Scala, Elixir, and more. GitHub announced their public API v4 would be built entirely on GraphQL in 2016. By 2018, GraphQL had grown large enough to form the GraphQL Foundation under the Linux Foundation, ensuring vendor-neutral governance of the specification.

5. What GraphQL Offers

GraphQL addresses REST's pain points through a fundamentally different approach to API design:

• Single endpoint, flexible queries: Instead of dozens of REST endpoints, GraphQL exposes a single endpoint (typically /graphql). Clients send a query describing exactly the data they need, and the server returns that exact shape. No over-fetching, no under-fetching.
• Client-driven data fetching: The client decides what data it gets, not the server. A mobile app can request a lightweight response while a web dashboard can request a richer one -- both hitting the same endpoint and the same schema.
• Strong type system: GraphQL APIs are defined by a schema written in SDL (Schema Definition Language). Every field has a type. Clients can introspect the schema to discover what's available, and tooling can validate queries at build time -- catching errors before deployment.
• Single round trip: A GraphQL query can traverse relationships in one request. Fetching a user, their posts, the comments on each post, and the authors of those comments can all happen in a single network call.
• Built-in evolution (no versioning): Fields can be deprecated with a reason rather than removed. New fields can be added without breaking existing clients. The schema evolves incrementally, eliminating the need for /v1, /v2 version prefixes.
• Real-time with subscriptions: GraphQL natively supports subscriptions -- persistent connections (typically WebSocket-based) where the server pushes updates to the client in real time when data changes.
• Introspection: Clients can query the schema itself to discover available types, fields, and relationships. This powers auto-complete in development tools, automatic documentation generation, and client code generation.

GraphQL didn't just solve over-fetching -- it shifted the power dynamic in API design from the backend team to the frontend team, letting clients request exactly the data they need.