GraphQL, from zero to governance — part 1
Facebook’s News Feed didn’t have an over-fetching problem. It didn’t have an API at all.
This series of posts is for anyone who works near APIs and has never had a reason to learn GraphQL — the same reader as What is an API? A plain-language guide and When two tools can’t talk, a person becomes the API. It assumes you know roughly what an app and a server are. There is no jargon in this post, but if you build APIs for a living, start at part 4, “Something has to actually go get it” (coming soon).
The screen
Think about what happens when you open a product page on any online store. It’s probably safe to assume that you’re familiar with the layout.
There’s a photo at the top, followed by a name and a description. You’ll also see a price, possibly a badge shouting some percentage off, a small line reading “3 left in stock,” a star rating with the number of reviews it has, a delivery estimate, and maybe “Deliver to your saved address.”
That’s nine things on one screen. If everything is working the way it is supposed to, it will load as a single page, and you’ll get a nice cohesive experience.
But behind the scenes, it’s probably not just one system doing the work (a single source holding everything for every page would be pretty inefficient). Every one of those nine items had to be found somewhere, named, placed into the correct spot in the layout template, and delivered to your phone in time to paint the screen. The photo and the price probably don’t come from the same place, nor do the star rating and the delivery estimate.
That raises the question: where does each of those nine things come from, and who decided what it’s called?
We’re just getting started today, but keep that mental model — every idea in this series hangs off that one screen.
┌────────────────────────────────────────┐ │ [ product photo ] │ │ │ │ Field Runner 3 │ │ Waterproof trail running shoe │ │ │ │ $129 [ -15% ] │ │ 3 left in stock │ │ │ │ ★ ★ ★ ★ ☆ 412 reviews │ │ │ │ Get it by Thu, Aug 20 │ │ Deliver to your saved address │ │ │ │ [ Add to cart ] │ └────────────────────────────────────────┘
GraphQL’s origin story
If you live in my world, you’ve probably absorbed an origin story for GraphQL. But that’s a pretty small world, so I’m going to assume that you haven’t.
Mobile apps got big around 2012. Phones were slow, networks slower, and the REST APIs of the day handed back fat blobs of JSON full of every piece of information about a user when the screen needed three fields. So Facebook (now Meta) built GraphQL to ask for exactly what it wanted and nothing more.
Nearly every explainer online opens on some version of that. I won’t sneer at it. It’s plausible, it’s cleanly told, and parts of it are true — slow networks were real, chatty round trips were real, and shipping fields the screen never rendered cost you something on a 2012 phone.
But that’s a simplified version of a real pain point.
What the announcement actually says
Go back to the source: Facebook’s engineering blog, September 14, 2015. Lee Byron authored the post that explains why Facebook built GraphQL in the first place.
It doesn’t describe an over-fetching problem so much as it describes not having an API at all.
Here’s the line, word for word: “We found ourselves for the first time needing an API data version of News Feed — which up until that point had only been delivered as HTML.”
The thing they needed to fetch had never existed as data. The News Feed was HTML and the mobile apps needed it as structured data for the first time. Slow and absent are different diagnoses, and Byron only wrote down one of them.
Then there’s REST, which the post puts on the table and walks away from. Byron’s words: “We evaluated our options for delivering News Feed data to our mobile apps, including RESTful server resources and FQL tables (Facebook’s SQL-like API).” The next sentence says why they passed on it: “We were frustrated with the differences between the data we wanted to use in our apps and the server queries they required.”
The complaint was not that REST sent too much but that the model was wrong. URLs and join tables on one side; a graph of objects, the way an app thinks about its data, on the other.
So when someone asks you what GraphQL is for, you don’t have to reach for the payload story. You can say the true thing: it started because a client needed to describe the data it wanted, and there was no way to describe it.
What they were actually after
If it wasn’t about trimming responses, what were they after? Two things.
First, the client says what it needs. The app describes the shape of the data it wants — those nine items, say — and the server hands back that exact shape without a single endpoint guessing on behalf of every other screen. The product page asks for its nine fields and gets nine fields back; the checkout screen asks for its own set.
This line gets underquoted: the server can keep adding fields for years without ever cutting a v2. Byron again: “We still support three years of released Facebook applications on the same version of our GraphQL API.”
That’s quite the change from a constantly versioned REST API: their GraphQL API grew for 3 years — new fields, new features, new product surfaces bolted on — and in all that time, no old app had to be rebuilt to keep running, and no /v2/ ever went up beside /v1/ to march everyone across.
The API was able to change shape underneath 3 years of already-shipped app versions without breaking one. A shipped app from 2012 and one from 2015 could hit the very same endpoint and both get what they asked for. Facebook had a name for the property: “version free.”
Something has to hold the list
If the client gets to describe exactly what it wants, then something, somewhere, has to hold the master list of what’s available to ask for. Every field. Every type. What’s a number, what’s a string, what’s allowed to be missing.
The client can’t ask for a field that isn’t on the list, and the server can’t invent one and expect the app to know it’s there. There has to be an agreed-on contract sitting in the middle that both sides can point at.
The word for this is a schema.
What a schema actually is — how it’s written, why arguments over it turn into standoffs, why it’s the one document both teams have to sign — is the next post in the series, “The schema is the contract”.
GraphQL didn’t replace REST
GraphQL didn’t kill REST, and it was never built to.
The person worth quoting on that is Byron himself, in a 2018 interview with Nordic APIs: “I’m certainly not one of those people who think I’ve invented the silver bullet here and everything should be GraphQL and there’s no room for anything else.” He calls REST “an amazing technology” and says he’d be sad to see it disappear.
GraphQL solved one specific problem: a client that needed to describe the shape of the data it wanted, back when no such description existed. It didn’t solve everything, and the people who built it never claimed it did.
[ screen ] ─────────── ??? ─────────── [ data ] the page where it all you see actually lives
The series diagram in its first state: the screen on the left, the data on the right, a question mark for everything in between. Each post fills in one piece of the middle; by the end, the series draws the whole path.
Read it in the wild
Open Byron’s announcement from September 14, 2015 — the one I’ve been quoting — and read the whole thing.
Then count how many times it mentions payload size, response size, or over-fetching.
It doesn’t.
Leave a Reply