Skip to content
API Design Learn/GraphQL at Scale
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Schema Federation

4 min read

You'll learn to

  • -Explain the problem federation solves: many teams, one graph, no shared file to fight over
  • -Read @key, @external and @requires, and watch a gateway split one query across two subgraphs
  • -Judge when federation is worth its complexity

A single GraphQL schema works well for one team or one service. Once an organization has several teams, each owning a different domain such as users, orders or inventory, but wanting one unified graph for clients, a single schema becomes a coordination bottleneck. Every team's change touches the same shared file, and no team can deploy on its own.

An Analogy: A Shopping Mall Directory

A shopping mall has one directory at the entrance, so you can find any shop. But each shop is run by its own business, with its own stock and its own opening hours. The directory is the unified graph, and each shop is a subgraph. A visitor never needs to know which business runs what.

The Problem Federation Solves

Apollo Federation, the dominant approach in practice, lets each team own and deploy its own subgraph, an independent GraphQL service for one domain. A gateway then composes all the subgraphs into one graph that clients query as if it were a single schema. One client query may touch types from three teams' services, with the gateway routing and stitching the results together.

The @key Directive: Identifying a Shared Entity

The Users subgraph owns the core User type
# --- users subgraph ---
type User @key(fields: "id") {
  id: ID!
  name: String!
  email: String!
}
The Orders subgraph extends User with its own fields, without owning the type
# --- orders subgraph ---
type User @key(fields: "id") {
  id: ID!
  orders: [Order!]!   # this subgraph adds a NEW field to a type it doesn't own
}

type Order {
  id: ID!
  total: Float!
}

@key(fields: "id") says that id is how this type is uniquely identified across subgraphs. The Users and Orders subgraphs both talk about the same logical User entity by that shared key. The gateway uses it to know which subgraph to call for which fields, and then merges the pieces into one User in the response.

@external and @requires: Depending on Another Subgraph's Data

Computing a field that needs data owned by a different subgraph
# --- orders subgraph ---
type User @key(fields: "id") {
  id: ID!
  email: String! @external          # not owned here, but referenced
  orderNotificationEmail: String! @requires(fields: "email")
}

@external marks a field this subgraph mentions but does not own, since email belongs to the Users subgraph. @requires(fields: "email") says that to compute orderNotificationEmail, the email value is needed first. The gateway fetches email from the Users subgraph before calling the Orders subgraph. The demo plays this out with two tiny subgraphs and a gateway. The client asks for a name, orders and the notification email. It never asks for email, but watch which subgraph calls are made.

Press Run: the gateway fetches email for the Orders subgraph without the client ever asking for it

Federation is a tool for organizational scaling, meaning independent ownership and deployment by separate teams. It is not mainly a performance trick. A well-designed single schema is simpler to reason about for a team small enough to coordinate, and should stay the default until team boundaries genuinely demand independence.

Interview Signal is part of Pro

See a real weak answer next to a real strong one for this exact topic.

Quiz is part of Pro

Test what you just read with a short quiz, and bank the XP.

Ready to Build This?

Design Schema Federation in the API Design Lab's GraphQL Mastery act.

Discussion0

Join the Discussion

Sign in to leave comments, reply to others, or like insights.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!