Federating multiple headless CMS sources with GraphQL

Federating multiple headless CMS sources with GraphQL fails when teams treat the gateway as an API proxy instead of a type-resolution layer. The result is schema collisions on shared fields, auth context drift across upstreams, and unpredictable build times. What works: strict namespace isolation per subgraph, a centralized context transformer, cache tags mapped to content IDs, and schema validation enforced in CI.

Schema isolation and type unification

Merging content endpoints triggers type conflicts on ubiquitous fields — slug, author, status. Run each CMS as an independent subgraph and extend shared entities through federation directives rather than duplicating them. The @key directive sets the primary identifier the router uses to stitch partial objects across services.

extend type Article @key(fields: "id") {
  id: ID! @external
  title: String! @external
  metadata: ContentMetadata @external
}

type ContentMetadata @key(fields: "canonicalUrl") {
  canonicalUrl: String!
  ogTitle: String
  keywords: [String!]
}

Defining types at their source avoids cascading validation errors during incremental builds. The gateway resolves references by querying the owning subgraph for the @key fields, then merges the payload — which scales across multi-tenant environments where content models diverge. The Apollo Federation documentation covers how query planning and entity resolution interact.

Resolver routing and context propagation

Authentication drift is a frequent failure: when JWT expiry windows or token scopes differ across upstream CMS providers, the gateway dispatches stale or mismatched credentials. A centralized context transformer standardizes identity before routing — it strips downstream-specific headers, validates token scope, and injects one normalized execution context.

import { ApolloServerPlugin } from '@apollo/server';
import { verifyAndScopeToken } from './auth-utils';

export const authContextPlugin: ApolloServerPlugin = {
  async requestDidStart({ request }) {
    const authHeader = request.http?.headers.get('authorization');
    if (!authHeader) throw new Error('Missing upstream auth context');

    const [scheme, token] = authHeader.split(' ');
    if (scheme.toLowerCase() !== 'bearer') {
      throw new Error('Invalid authorization scheme');
    }

    const validatedToken = await verifyAndScopeToken(token, request.operationName);

    return {
      willSendResponse({ response }) {
        // Enforce predictable cache headers at the gateway boundary
        response.http?.headers.set('Cache-Control', 'public, max-age=60, stale-while-revalidate=300');
      }
    };
  }
};

Log resolver latency per subgraph at the gateway so you can isolate an upstream bottleneck before it surfaces as a frontend timeout. Attach a correlation ID to every dispatched request for distributed tracing across CMS boundaries.

The context transformer sits between the client and the CMS subgraphs, normalizing identity before any upstream dispatch:

sequenceDiagram
  participant Client as Frontend
  participant GW as Gateway
  participant CTX as Context transformer
  participant CMS as CMS subgraph
  Client->>GW: "query + authorization header"
  GW->>CTX: "strip headers, validate scope"
  CTX-->>GW: "normalized execution context"
  GW->>CMS: "resolve @key fields (correlation ID)"
  CMS-->>GW: "partial entity"
  GW-->>Client: "merged response + Cache-Control"

Caching across fragmented origins

CDN caching assumes a single origin with consistent ETag headers. Federation fragments each response across upstreams, breaking that assumption and causing stale content or needless Jamstack rebuilds. Propagate cache tags with @cacheControl: tag per content type and version, then purge targeted fragments via webhook. The MDN HTTP Caching reference explains why explicit max-age and stale-while-revalidate beat opaque CDN defaults here. Map cache tags directly to CMS content IDs so a webhook payload purges only affected fragments instead of whole route caches. Paired with incremental static regeneration (ISR), this keeps content fresh without sacrificing build performance.

N+1 mitigation

Sequential resolver execution across federated boundaries is the classic N+1 trap: fetch relational data from the primary CMS, then query an identity provider or secondary store per record, exhausting connection pools and inflating TTFB. Deploy DataLoader at the subgraph level to batch identical key requests into one upstream call, and use CMS-specific include/populate parameters to pre-fetch relations before they reach the federation layer.

Set per-subgraph timeouts and circuit breakers that fail fast on a degraded upstream, returning cached fallbacks or partial responses rather than blocking the whole graph. Add query complexity analysis at the router to reject deeply nested client requests.

Governance and CI enforcement

Schema contracts need teeth. Agency engineers and content teams routinely add ad-hoc fields or alter type definitions without coordination, which breaks downstream TypeScript generation and client type safety. Enforce schema registry validation in CI: require pull requests to pass graphql-codegen validation and contract testing before merge, and block any change that breaks a shared @key entity. Track resolver execution time, cache hit ratio, and type-generation success as DX metrics. For router-level optimizations and cross-service query planning, see Advanced GraphQL Federation Patterns.

Conclusion

Federating CMS sources turns fragmented content into one type-safe layer when you isolate namespaces, normalize context centrally, tag caches at the content-ID level, and gate schema changes in CI. Skip any one of those and the gateway becomes the bottleneck it was meant to remove.