Most GraphQL material explains schemas, queries, mutations, resolvers, and pagination. That is necessary, but it is not enough once the graph is split across multiple backend services. At that point, the important question becomes architectural:
How does one client request become work across multiple backend services without exposing that backend topology to the client?
.
.
.
GraphQL federation
Apollo describes federation as a way to combine multiple APIs into a single federated GraphQL API. The client sends one GraphQL request to the router, and the router coordinates the API calls needed to produce one response.
Without federation, teams usually end up with one of two uncomfortable options. Either clients learn too much about backend service boundaries, or a central API layer becomes responsible for manually stitching together everything. The first option couples frontend code to backend topology. The second often turns into a slow-moving aggregation layer owned by nobody cleanly.
Federation takes a different route. Backend teams can own separate parts of the graph as subgraphs, while clients continue to query a single API shape.
The client does not need to know which service owns users, billing, schedules, permissions, or analytics. It should only know the graph contract.
The supergraph
Subgraphs are what backend teams own. The supergraph is what clients query. The gateway uses the supergraph to decide where each part of the operation should run.
A subgraph is a GraphQL schema owned by one backend service or domain. It contributes types, fields, and relationships to the overall graph.
The supergraph is the composed result of those subgraphs. It contains the information the gateway needs to understand field ownership and build a plan for executing an operation across one or more services.
.
.
.
The gateway
It is tempting to think of a GraphQL gateway as a simple proxy in front of services. That model is too weak.
A proxy forwards requests. A federated GraphQL gateway understands the operation, validates it against the composed graph, builds a query plan, sends sub-requests to the relevant subgraphs, and assembles the response back into the shape the client requested.
Apollo Gateway's documentation explains that the gateway processes the supergraph SDL on startup. That SDL includes routing information for subgraphs, and the gateway uses it to create query plans that can execute across one or more subgraphs.
When a client asks for fields owned by a single subgraph, the gateway can send one sub-request. When the operation crosses ownership boundaries, the gateway has to coordinate multiple subgraph calls. Some of those calls may be independent. Some may depend on data returned from an earlier step.
The client still sees one GraphQL response.
.
.
.
Schema publication
In Apollo terminology, the gateway can be initialized with a supergraph SDL. A static supergraph means the gateway needs a restart to pick up schema changes. Apollo's gateway describe dynamic supergraph updates, where the gateway receives an initial supergraph and can later update it through a callback. Polling, webhooks, and file watchers are examples of update mechanisms.
It creates two separate architectural paths:
- The control plane publishes and validates schema changes.
- The data plane serves live GraphQL requests using the currently active supergraph.
The control plane is where subgraph schemas are registered, composed, checked, and promoted. The data plane is where client operations are planned and executed.
A field can exist in a subgraph implementation but still fail through the gateway if the composed supergraph has not been updated. A schema can compose locally but not be active in the runtime gateway. A backend service can be healthy while the graph artifact consumed by the gateway is stale.
.
.
.
Apollo Federation: federated schemas
Apollo Gateway: updating the supergraph schema
Top comments (0)