GraphQL Federation Isn’t Just an API Problem — It’s an Organisational One
Working with GraphQL Federation can feel like more pain than power. Here’s a firsthand account of what to expect — and why it’s not just a tech problem, but an organisational one.
In my previous team, we were dependent on two fairly large federated graphs to get data. Working with them often left a sour aftertaste in our developers’ mouths. These APIs weren’t doing what we expected them to do — abstract away complexity. Instead, they leaked it.
The industry has come to expect that good APIs should mask complexity. A bit like the image below — the system should be deep, but the surface should feel simple.
But with federated GraphQL, our developers were overwhelmed.
They were exposed to a tangle of entities and relationships. Figuring out what each entity meant in a given context — and how it was relevant to the task at hand wasn’t trivial. Developers now had to understand not only their own domain, but also navigate data models several layers removed from their own domain. The cognitive load spiked.
I work at a company that’s close to 100 years old. Its core product has a deeply complex data model, federated across many teams and organisational boundaries. The teams that own systems of record tend to sit close to their business units. The teams that build applications with that data are often located in completely different parts of the org — sometimes unaware the upstream team even exists.
In a world without GraphQL federation, application teams would spend a bulk of their time navigating the org structure, trying to understand who owns what and where to get what data from. You could argue that this is solvable with an API gateway too — and you’d be partially right. But the GraphQL protocol offers something else: dynamic query building, allowing clients to fetch exactly what they need without the back-and-forth of endpoint negotiations.
That brings me to what I believe is the real shift we need to make when working with GraphQL federation.
Federation Doesn’t Make the Org Disappear
While federated GraphQL helps application teams avoid navigating complex org structures to find data, it doesn’t make those structures disappear. Often, the federated graph is owned by a dedicated platform team — and it’s unreasonable to expect this team to understand the full domain model across all business units.
Yet, that’s exactly what tends to happen.
Because the federated graph presents a unified interface, consuming teams often assume that the graph team can resolve any data-related issue. This expectation becomes especially painful during incidents. When part of the graph fails, the federation team becomes the first line of defence — even though the root cause may lie in a downstream team’s domain.
In my experience consuming two large federated graphs, I learned that it’s important for both product teams and federation teams to see themselves as enablers — not as omniscient owners.
For product teams, this means developing empathy for the platform team and resisting the urge to escalate every ambiguity or failure to them.
For graph teams, this means investing in the right mechanisms: clear ownership documentation, feedback loops with domain teams, and tools to route questions or failures to the right owners quickly.
Federation doesn’t eliminate complexity. But it can distribute the responsibility for managing it — if we design the system and the expectations right.
What to Expect (and Accept)
It’s not just an API — it’s a query language. Treating it like a traditional REST abstraction will lead you into trouble.
The complexity in the data model is essential, not accidental. It reflects your domain. You’re not supposed to fully abstract it away.
Federated GraphQL solves an organisational problem as much as it solves a technical one. It connects people who otherwise wouldn’t know they need to talk to each other.
All this not to imply that the GraphQL abstractions are broken, only to say that they reveal the underlying org structures a lot more than might have been intended. That transparency is a double-edged sword: it gives you flexibility and discovery, but it also surfaces complexity, shifts accountability, and demands clearer expectations. Acknowledging that trade-off is the first step toward building better systems and better expectations.