GraphQL Federation Pattern

Compose a unified GraphQL API from independently deployed subgraph services using Apollo Federation

When to Use

• Multiple teams own different domains and need independent deployment
• A monolithic GraphQL schema has grown too large for one service
• You need to extend types across service boundaries (e.g., adding

  orders

  to

  User

  from the orders service)
• Migrating from schema stitching to a standards-based composition model

Instructions

1. Each subgraph owns its domain types. The users service defines

   User

   , the orders service defines

   Order

   . No type is defined in two places — types are extended across boundaries.

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

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

2. Use

   @key

   to mark entity types. An entity is a type that can be referenced and extended by other subgraphs. The

   @key

   directive specifies which fields uniquely identify the entity.

3. Extend entities in other subgraphs with stub types. The orders service references

   User

   without redefining it — it provides only the key field and adds new fields.

# orders subgraph
type User @key(fields: "id") {
  id: ID!
  orders: [Order!]!
}

type Order @key(fields: "id") {
  id: ID!
  total: Money!
  status: OrderStatus!
  customer: User!
}

4. Implement

   __resolveReference

   for each entity. This resolver is called by the gateway when it needs to hydrate a stub entity. It receives the key fields and returns the full object.

const resolvers = {
  User: {
    __resolveReference: (ref: { id: string }, { dataSources }) => {
      return dataSources.users.findById(ref.id);
    },
  },
};

5. Use the Apollo Router (or Gateway) to compose subgraphs. The router fetches schemas from each subgraph, composes them into a supergraph, and routes incoming queries to the appropriate subgraphs.

# supergraph-config.yaml
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

6. Use

   @shareable

   for fields that multiple subgraphs can resolve. In Federation v2, fields are exclusive by default. Mark fields

   @shareable

   when multiple subgraphs need to return the same field.

7. Use

   @override

   to migrate fields between subgraphs. When moving a field from one subgraph to another, the new owner uses

   @override(from: "old-subgraph")

   to claim resolution without a breaking change.

8. Use

   @external

   ,

   @provides

   , and

   @requires

   for computed fields.

   @requires

   tells the gateway to fetch specified fields from the owning subgraph before calling the current resolver.

# shipping subgraph
type Order @key(fields: "id") {
  id: ID!
  weight: Float @external
  shippingCost: Float @requires(fields: "weight")
}

9. Run composition checks in CI. Use

   rover subgraph check

   to validate that schema changes in one subgraph do not break the composed supergraph before deploying.

10. Keep the gateway stateless. The router/gateway should not contain business logic — it composes and routes. All business logic lives in subgraphs.

Details

Federation v1 vs. v2: Federation v2 (current) uses

@link

to import federation directives, supports

@shareable

,

@override

,

@inaccessible

, and progressive

@override

for safe migrations. Prefer v2 for new projects.

Query planning: The gateway decomposes incoming queries into subgraph fetches. A query for

user { name orders { total } }

fetches

name

from the users subgraph, then fetches

orders

from the orders subgraph using the user's

id

as the reference key. This happens transparently.

Performance considerations:

• Entity references add network hops — the gateway calls

  __resolveReference

  on the owning subgraph
• Use

  @provides

  to return extra fields alongside entities to reduce follow-up fetches
• Batch entity lookups in

  __resolveReference

  using DataLoader

Ownership rules:

• A type's

  @key

  fields must be resolvable by the defining subgraph
• Only one subgraph should define a field (unless

  @shareable

  )
• Value types (types without

  @key

  ) must be identical across subgraphs

Common mistakes:

• Circular entity references that cause infinite gateway loops
• Missing

  __resolveReference

  — the gateway cannot hydrate the entity
• Changing

  @key

  fields without updating all referencing subgraphs
• Putting too many types in one subgraph, recreating the monolith

Source

https://www.apollographql.com/docs/federation/

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.