This post is for you if you can answer "yes" to all/most of the questions below:
- You've built APIs before (or at least consumed them).
- You've heard the "REST vs GraphQL" debate and felt confused about which one is "better."
- You're tired of surface-level comparisons that just list features.
- You want to understand why these technologies exist, not just how to use them.
- You're the kind of developer who asks "why?" before "how?"
If you nodded along, stick around. This isn't another comparison table. This is the story of two philosophies born in different eras, solving different problems, and somehow ending up at the same dinner table in 2026.
The Misconception That Needs to Die
Let me start with something that might hurt: REST was never designed for building APIs.
Wait, what?
I know. I had the same reaction when I first read Roy Fielding's 2000 dissertation properly. As a trainer who's been explaining REST to developers for years, this was humbling.
Consider this: Roy Fielding wasn't some random PhD student who sat in an ivory tower and came up with a bright idea. He was deeply embedded in the web's early development. He co-authored HTTP 1.0 and 1.1. He co-founded the Apache HTTP Server project. The man literally helped build the plumbing of the internet.
REST (Representational State Transfer) was his doctoral dissertation's attempt to describe and formalize the architecture of the World Wide Web itself. The entire web is supposed to be RESTful. REST isn't specifically about JSON APIs or GET /users/123. In fact, Fielding doesn't mention web APIs much in his dissertation at all.
This distinction matters more than most developers realize.
So How Did REST Become the "API Standard"?
Here's where history gets interesting.
In the mid-2000s, developers were burning in SOAP hell. SOAP (Simple Object Access Protocol) was verbose, complicated, and required understanding a maze of XML specifications just to say "Hello World." There's nothing simple about it, by the way.
Developers needed an escape route. They needed their own four-letter acronym to rally behind.
And REST was right there. It was simple. It used HTTP methods everyone already knew. It didn't require a 400-page PDF manual (looking at you, Salesforce's first API). When Ruby on Rails dropped SOAP support in 2007, David Heinemeier Hansson essentially said SOAP was overly complicated, and the migration was on.
The problem? Most of what we call "REST APIs" today would make Roy Fielding cringe. As he clarified in a 2008 blog post:
"A REST API should be entered with no prior knowledge beyond the initial URI and set of standardized media types."
Most APIs hardcode everything. Your /api/v1/users endpoint with JSON responses? That's not really RESTful in the pure sense. It's just "HTTP-based API that kinda follows some REST principles."
But does that matter? Honestly, not really. What matters is that REST gave us:
- Simplicity: HTTP verbs (GET, POST, PUT, DELETE) mapped to CRUD operations
- Statelessness: Each request contains everything needed to process it
- Cacheability: HTTP caching worked out of the box
- A shared vocabulary: Developers worldwide could talk to each other
REST became the lingua franca of APIs. And that's powerful.
Enter Facebook's Mobile Nightmare (2011)
2011, Menlo Park. Facebook had a problem.
Their iOS and Android apps were thin wrappers around mobile web views—and they were failing. Slow load times. Frequent crashes. Users abandoning the app entirely. Mark Zuckerberg would later call this approach "one of the biggest mistakes we've made as a company."
Three engineers—Lee Byron, Dan Schafer, and Nick Schrock—took on the challenge of rebuilding the News Feed as a native iOS app. They hit a wall immediately: the backend was architected for web pages, not mobile clients.
Consider what a single News Feed story contains:
- Author name and profile picture
- Post content (text, images, or video)
- Like count
- Comments (each with its own author, timestamp, and content)
- Shares (which are themselves posts, recursively containing all of the above)
With a traditional REST approach, loading one story could require:
GET /posts/123
GET /users/456 ← author
GET /posts/123/comments
GET /posts/123/likes
GET /users/789 ← commenter 1
GET /users/101 ← commenter 2
...and so on
On a 2012-era 3G connection, this was death by a thousand round trips.
REST: Multiple Round Trips
GraphQL: Single Round Trip
(To be fair: REST has patterns like embedded resources (?include=author,comments) and sparse fieldsets that can reduce this. But they require deliberate design work—they're not built into the paradigm the way GraphQL's single-query model is.)
They tried the existing internal REST-like API. They tried FQL (Facebook Query Language), their SQL-like query language. But both had the same fundamental problem: the data was relational and graph-like, but the APIs were tabular and rigid.
As Lee Byron put it: "You've got a square-peg, round-hole problem on the server and a round-peg, square-hole problem on the client."
The solution? Stop treating data like tables. Start treating it like what it actually is: a graph.
They called the prototype "SuperGraph." The world would eventually know it as GraphQL.
The Philosophy Difference
This is where it gets philosophical. Bear with me: this is the part that'll actually make you think differently about APIs.
REST's Philosophy: The Web of Resources
REST thinks in resources. Every thing is a thing with an address.
- A user is a resource:
/users/123 - A post is a resource:
/posts/456 - Comments are resources:
/posts/456/comments
You interact with these resources using standard HTTP verbs. The server decides what data you get back. The client adapts.
Think of it like a library catalog system: every book has a unique call number (its URL), you follow standard procedures to borrow or return it (HTTP verbs), and the librarian decides what information goes on the checkout slip (the response). You can't ask for "just the first chapter"—you get the whole book.
This made perfect sense for the web. URLs, HTTP methods, caching—it all mapped beautifully to how browsers worked.
GraphQL's Philosophy: The Client Knows Best
GraphQL thinks in queries. The client describes exactly what it wants, and the server fulfills that request.
query {
user(id: "123") {
name
avatar
posts(first: 5) {
title
likes
comments(first: 3) {
text
author {
name
}
}
}
}
}
One request. Exactly the data needed. Nothing more, nothing less.
This made perfect sense for mobile apps. Battery life matters. Bandwidth costs money. Every unnecessary byte is a crime.
The Core Tension
The fundamental difference comes down to this:
| Aspect | REST | GraphQL |
|---|---|---|
| Who decides the data shape? | Server | Client |
| How many endpoints? | Many (per resource) | One |
| Data fetching | Fixed responses | Flexible queries |
| Versioning | URL-based (/v1/, /v2/) |
Schema evolution (deprecation) |
| Caching | Built into HTTP | Requires additional tooling |
Neither is "better." They're solving different problems with different constraints.
The takeaway: REST asks "what resource do you want?" while GraphQL asks "what data do you need?" That one-word difference—resource vs data—explains almost every architectural decision that follows.
The Evolution: 2012 to 2026
Let's trace how both have evolved, because this is where the story gets rich.
REST's Evolution
2000-2010: The Wild West
- REST becomes the anti-SOAP
- Everyone interprets it differently
- OpenAPI (then Swagger) emerges to bring structure
2010-2020: Maturation
- JSON becomes the default (goodbye XML!)
- API design best practices solidify
- HATEOAS (Hypermedia as the Engine of Application State—the idea that API responses should include links to related actions) remains mostly theoretical
- OpenAPI 3.0 standardizes documentation
2020-2026: The Pragmatic Era
- REST stops pretending to be "pure"
- Hybrid patterns emerge (REST serving GraphQL gateways)
- AI-driven systems start consuming REST APIs en masse
- REST becomes the stable, boring, reliable choice—and that's a compliment
- Spring Framework 7 adds first-class API versioning (September 2025)—more on this below
GraphQL's Evolution
2012-2015: The Secret Years
- Built internally at Facebook
- Powers iOS app rewrite (August 2012)
- Users consume 2x more feed stories than the HTML5 app
- Remains internal for 3 years
2015: The Open-Source Moment
- Facebook publishes the GraphQL specification
- Reference implementation released
- GitHub builds their public GraphQL API (2016)
- Adoption begins slowly
2017-2020: The Hype Cycle Peak
- Apollo GraphQL emerges as the dominant tooling company
- Every startup wants GraphQL
- "GraphQL replaces REST" becomes the hot take
- Reality: most teams struggle with complexity
2020-2024: The Sobering
- N+1 query problems become well-known (when a single GraphQL query triggers dozens of separate database calls—one for the parent, plus one for each child)
- Security concerns (query depth, complexity attacks) require attention
- Teams realize GraphQL needs infrastructure investment
- Federation emerges for microservices architecture
The N+1 Problem Visualized:
1 query for users + N queries for each user's posts = N+1 database hits. Solution: DataLoader batches the N queries into 1.
2025-2026: The Maturation
- 10 years of GraphQL celebrated at GraphQLConf 2025
- Apollo Connectors released—REST APIs can now be declaratively integrated into GraphQL schemas
- GraphQL Foundation standardizes Federation
- MCP (Model Context Protocol) shows early promise for bringing GraphQL to AI agents—still emerging, but worth watching
- The "GraphQL vs REST" debate finally calms down
The takeaway: Both technologies matured by acknowledging their weaknesses. REST stopped pretending versioning wasn't needed; GraphQL stopped pretending it was simple. The survivors are the pragmatists.
Where Are We Now? (January 2026)
Let me share some numbers that tell the real story:
- REST still dominates: 93% of teams use REST, while 33% use GraphQL (Postman State of the API 2025)
- GraphQL production usage has reached 61% among surveyed organizations (Hygraph GraphQL Report 2024)
- Enterprise adoption is accelerating: Gartner predicts 60%+ of enterprises will use GraphQL in production by 2027, up from less than 30% in 2024 (The New Stack)
- Hybrid approaches are becoming the norm—companies running both report higher satisfaction than those committed exclusively to either
(Note: We're focusing on REST and GraphQL here, but gRPC deserves mention as the third major player—especially for high-performance internal microservice communication.)
Pause for a moment: Based on what you've read so far, which philosophy would you lean toward for a mobile-first e-commerce app? Hold that thought—we'll come back to it.
The Spring Framework 7 Plot Twist
Here's something that dropped in September 2025 that perfectly encapsulates the state of this debate.
Spring Framework 7 (releasing November 2025) added first-class API versioning support. For those of us in the Java/Spring world, this is huge. Rossen Stoyanchev from the Spring team wrote about it, and the irony is thick.
While this is Java-specific, it signals a broader industry shift. NestJS has been moving toward declarative versioning, FastAPI added versioning patterns in recent releases, and even Go frameworks like Gin are seeing community pressure for standardized approaches. The enterprise world is collectively admitting: versioning isn't going away, so let's do it right.
The key insight: versioning has always been REST's Achilles heel. Do you version in the URL (/v1/users)? In a header (API-Version: 1.1)? In the media type (application/vnd.myapi.v1+json)? Everyone has opinions. Nobody agrees. There's no standard.
And guess what Roy Fielding, the creator of REST, says about API versioning? He advises against it.
Yet here's Spring, the enterprise Java juggernaut, adding official versioning support because, as the issue tracker showed, implementing it properly "requires a lot of work."
The Mechanics
The idea is simple: configure your versioning strategy once, then let the framework handle routing based on version metadata. No more hacking URL patterns or writing custom interceptors. The framework treats version as a first-class routing concern, just like HTTP method or content type.
The new ApiVersionStrategy lets you configure versioning once and use it everywhere:
@Configuration
public class WebConfiguration implements WebMvcConfigurer {
@Override
public void configureApiVersioning(ApiVersionConfigurer configurer) {
configurer.useRequestHeader("API-Version");
}
}
Or in Spring Boot 4, just a property:
spring.mvc.apiversion.use.header=API-Version
Then your controllers become beautifully explicit:
@RestController
public class AccountController {
@GetMapping(path = "/account/{id}", version = "1.1")
public Account getAccountV1() {
// Version 1.1 implementation
}
@GetMapping(path = "/account/{id}", version = "2.0")
public AccountV2 getAccountV2() {
// Version 2.0 implementation
}
}
They even added baseline versions ("1.2+") so you can say "this endpoint works for version 1.2 and all future versions until something breaks," reducing the need to duplicate controller methods for unchanged endpoints.
For deprecation? Built-in support for RFC 9745 and RFC 8594 headers (Deprecation, Sunset, Link). The server can actually tell clients "hey, you're using an old version, here's when it dies."
The Philosophical Implication
This is REST admitting something GraphQL advocates have said for years: managing API versions is hard, and most teams do it poorly.
But GraphQL's answer to versioning is fundamentally different: "don't version—evolve." You add new fields, deprecate old ones, but you never break the schema. The query language itself allows clients to request only what they need, so adding fields doesn't break anything.
type User {
id: ID!
name: String!
email: String!
# New field - old clients just don't request it
avatar: String
# Deprecated field - still works, but marked for removal
legacyId: Int @deprecated(reason: "Use id instead")
}
But here's the reality check: GraphQL's "no versioning" philosophy requires discipline. You can't remove fields easily. You can't rename them. Every change must be additive. And if you've ever worked in a fast-moving team, you know how hard it is to maintain that discipline forever. (This is why mature GraphQL teams use Schema Registries with breaking change detection in CI/CD—the tooling enforces what humans forget.)
| REST's Approach | GraphQL's Approach |
|---|---|
Explicit versions (v1, v2) |
Schema evolution (deprecation) |
| Multiple endpoints coexist | Single endpoint, schema changes |
| Breaking changes are clear | Additive-only changes encouraged |
| Clients choose their version | Clients adapt to schema |
Spring's approach says: "Look, versioning is happening. Let's make it first-class so teams do it well instead of poorly."
Neither is wrong. They're just different philosophies:
- GraphQL: "Let's design a system where versioning isn't needed."
- REST (Spring 7): "Let's accept that versioning happens and make it painless."
Here's what mature teams are doing in 2026:
- REST for public APIs: Simple, documented, universally understood
- GraphQL for internal composition: Complex queries, mobile apps, dashboard applications
- GraphQL Gateways over REST: Apollo Connectors and similar tools let you keep REST backends while getting GraphQL benefits
As Matt DeBergalis (Apollo CTO) said recently: "What would have been a yearlong rewrite has become a two-day implementation."
So, Which Should You Learn?
If you're asking me as a trainer who has taught both to hundreds of developers, here's my honest answer:
Learn REST first. Not because it's better, but because:
- It builds on HTTP fundamentals you need anyway
- It's what you'll encounter in 80% of real-world projects
- It teaches you to think in resources, which is universally useful
- Debugging REST is simpler
Then learn GraphQL. Because:
- It will change how you think about data relationships
- Mobile and frontend-heavy projects increasingly demand it
- Schema-first development is a powerful paradigm
- The tooling ecosystem is now mature enough
But most importantly: Learn why they exist. The history matters. The philosophy matters. When you understand that REST was about describing the web's architecture and GraphQL was about solving Facebook's mobile crisis, you stop asking "which is better?" and start asking "which is right for this problem?"
The Real Lesson
After years of teaching this, one insight stands out: technologies are not neutral. They carry the DNA of the problems they were born to solve.
REST carries the DNA of the early web—documents, links, browsers, caching. When your problem looks like that, REST shines.
GraphQL carries the DNA of Facebook's News Feed—complex relationships, mobile constraints, constantly evolving schemas. When your problem looks like that, GraphQL shines.
The mistake is treating them as competing answers to the same question. They're not. They're different questions altogether:
- REST asks: "How do we create a simple, scalable way to access resources over HTTP?"
- GraphQL asks: "How do we let clients efficiently query complex, interconnected data?"
Both questions are valid. Both have elegant answers. The skill is in knowing which question you're really asking.
Your Turn
I'd love to hear from you in the comments:
- What's been your experience with REST vs GraphQL?
- Have you ever tried running both in the same project?
- What problems did each solve (or create) for you?
And if you're still figuring this out—that's okay. I was too, for years. The best developers I know are the ones who stay curious, keep questioning, and never settle for "because that's how it's done."
Keep learning. Keep building. And remember: the technology is just a tool. The thinking is what matters.
If this helped you understand the REST vs GraphQL landscape a little better, consider sharing it with someone who's asking the same questions. Let's raise the level of discourse beyond "X is dead, Y is the future."
References & Further Reading:
- Fielding, Roy. Architectural Styles and the Design of Network-based Software Architectures (2000). Link
- Byron, Lee. "Introducing the GraphQL Foundation" (2018). Link
- Meta Engineering. "GraphQL: A data query language" (2015). Link
- Two-Bit History. "Roy Fielding's Misappropriated REST Dissertation" (2020). Link
- GraphQL Foundation. "Federation Documentation" (2025). Link
- Stoyanchev, Rossen. "API Versioning in Spring" (2025). Link
- Stoyanchev, Rossen. "API Versioning Talk at Spring I/O" (2025). Video
Top comments (0)