Apollo Federation: GraphQL Supergraph Architecture Guide

Apollo Federation lets you split a large GraphQL schema across independent services (subgraphs) owned by separate teams, then compose them into one unified supergraph. Clients see a single API; your teams stay decoupled.

Subgraph Definition with @key

Each subgraph declares its entity types with @key. The Users subgraph owns the User entity; the Orders subgraph extends it with order data:

# users-subgraph schema.graphql
type User @key(fields: "id") {
  id: ID!
  name: String!
  email: String!
}

type Query {
  user(id: ID!): User
  me: User
}

# orders-subgraph schema.graphql
# Reference User without redefining all its fields
type User @key(fields: "id") {
  id: ID!
  orders: [Order!]!
}

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

enum OrderStatus { PENDING SHIPPED DELIVERED }

type Query {
  order(id: ID!): Order
}

Subgraph Server Setup (Node.js)

Use @apollo/subgraph to build each federation-aware subgraph and implement the __resolveReference function for entity resolution:

import { ApolloServer } from '@apollo/server';
import { buildSubgraphSchema } from '@apollo/subgraph';
import { gql } from 'graphql-tag';

const typeDefs = gql`
  type User @key(fields: "id") {
    id: ID!
    name: String!
    email: String!
  }
  type Query { user(id: ID!): User }
`;

const resolvers = {
  User: {
    // Called when another subgraph references this entity by key
    __resolveReference(ref: { id: string }) {
      return db.users.findById(ref.id);
    },
  },
  Query: {
    user: (_: unknown, { id }: { id: string }) => db.users.findById(id),
  },
};

const server = new ApolloServer({
  schema: buildSubgraphSchema({ typeDefs, resolvers }),
});

// Start on a unique port per subgraph, e.g. 4001

Composing with Rover CLI

Use rover supergraph compose to combine subgraph schemas locally, or publish to Apollo Studio for managed composition:

# supergraph.yaml — compose config
federation_version: =2.4.0
subgraphs:
  users:
    routing_url: http://users-service:4001/graphql
    schema:
      subgraph_url: http://users-service:4001/graphql
  orders:
    routing_url: http://orders-service:4002/graphql
    schema:
      subgraph_url: http://orders-service:4002/graphql

# Compose locally and output the supergraph SDL
rover supergraph compose --config supergraph.yaml > supergraph.graphql

# Start the Apollo Router with the composed schema
./router --supergraph supergraph.graphql --config router.yaml

# Publish a subgraph schema to Apollo Studio (CI step)
rover subgraph publish my-graph@prod \
  --name users \
  --schema ./users-schema.graphql \
  --routing-url https://users.prod.internal/graphql

Federation vs Schema Stitching vs Monolith