Federated GraphQL & Apollo Supergraphs: Composing Distributed Microservices into a Single API

The Monolithic GraphQL Bottleneck

• Merge Conflicts & Broken Deployments: Every team touched the same schema files. A syntax error committed by the payments team blocked releases for the authentication and catalog teams.
• Single Point of Failure: If the monolithic GraphQL server crashed, every client application went down.
• Loss of Domain Ownership: Microservices are supposed to own their own data and lifecycles. Forcing them through a monolithic intermediary destroyed team autonomy.

Anatomy of a Supergraph: Federation 2 Architecture

[Web & Mobile Clients]
         │  (Single GraphQL Request)
         ▼
[Apollo Router Gateway (Written in Rust)]
         │  (Query Planning & Subgraph Composition)
         ├───────────────────┼───────────────────┐
         ▼                   ▼                   ▼
  [Users Subgraph]    [Orders Subgraph]   [Products Subgraph]
  (Python / FastAPI)    (Node.js / TS)      (Go / Rust)

1. Subgraphs: Independent GraphQL services that define schemas for their own domain.
2. Entities (@key): Types that can be referenced and extended across multiple subgraphs (e.g., a User type defined in the Auth service, but extended with an orders field by the Orders service).
3. Supergraph Schema: The compiled composition of all subgraphs.
4. Apollo Router: A blazingly fast, multi-threaded binary written in Rust that receives client queries, plans an execution graph, and fetches data in parallel across downstream subgraphs.

Hands-On: Extending Entities Across Subgraphs

1. The Users Subgraph (Auth Service)

graphql
# users-subgraph.graphql
extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.0", import: ["@key"])

type User @key(fields: "id") {
  id: ID!
  email: String!
  username: String!
}

type Query {
  me: User
}

2. The Orders Subgraph (E-Commerce Service)

graphql
# orders-subgraph.graphql
extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.0", import: ["@key"])

# Reference the User entity from the Users service
type User @key(fields: "id") {
  id: ID!
  orders: [Order!]! #  Enrich User with domain-specific fields!
}

type Order {
  id: ID!
  amount: Float!
  status: String!
  createdAt: String!
}

The Resolver Implementation in Python (Strawberry GraphQL):

python
# orders_service/schema.py
import strawberry
from typing import List

@strawberry.federation.type(keys=["id"])
class User:
    id: strawberry.ID

    @strawberry.field
    async def orders(self) -> List["Order"]:
        # Query orders database for this user id
        return await fetch_orders_for_user(self.id)

@strawberry.type
class Order:
    id: strawberry.ID
    amount: float
    status: str

@strawberry.type
class Query:
    pass

schema = strawberry.federation.Schema(query=Query, types=[User, Order])

Client Queries & The Execution Plan

graphql
query GetUserProfileWithOrders {
  me {
    username # Fetched from Users Subgraph (FastAPI)
    email    # Fetched from Users Subgraph (FastAPI)
    orders { # Fetched from Orders Subgraph (Python)
      id
      amount
      status
    }
  }
}

What Apollo Router Does:

1. Receives the incoming GraphQL document.
2. Automatically generates an Execution Plan:
   • Step 1: Send query to Users Subgraph to resolve me { id, username, email }.
   • Step 2: Extract id from response and invoke Orders Subgraph with _entities(representations: [{ __typename: "User", id: $id }]).
   • Step 3: Stitch together the responses in RAM and return a single JSON object to the client in under 15ms.

Why Apollo Router (Rust) Replaced Apollo Gateway (Node.js)

• 10x Lower Latency: P99 latency dropped from 35ms to under 3ms.
• 12x Higher Throughput: Substantially higher request concurrency per CPU core.
• Memory Footprint: Consumes a fraction of the RAM of Node.js instances.

Share this article

Comments