GraphQL Federation
Learn what GraphQL Federation is and how to combine multiple GraphQL APIs called subgraphs into one unified API (supergraph), and serve data from a single endpoint using a GraphQL gateway.
What is GraphQL Federation?
As GraphQL APIs grow, they become harder to maintain. Teams step on each other's toes, deployments get risky, and making changes becomes slow.
GraphQL federation solves these issues by letting you break down your monolithic GraphQL API into smaller parts, called subgraphs. Each team can work on their domain independently and deploy at their own pace.
Thanks to the process called schema composition, the integrity of those subgraphs is validated and their schemas are combined into one unified schema, the supergraph.
GraphQL clients interact with a single http endpoint served by GraphQL gateway (often called GraphQL router) that resolves data of your federated API.
Why GraphQL Federation?
Federated architecture is a powerful, yet advanced concept.
While it introduces additional complexity, the benefits make it a compelling choice for growing organizations.
Domain-Driven Design
GraphQL federation is perfect for domain-driven design or when you want to write GraphQL APIS in different languages. It allows teams to contribute data from their isolated GraphQL APIs (subgraphs) to the shared space called Supergraph.
This way, each team can focus on their domain and iterate faster, without being blocked by other teams.
Scalability
Subgraphs can be scaled independently based on their specific requirements, and deployed on their own schedule.
Different parts of the API can evolve at different paces, and making changes in the GraphQL schema no longer requires coordination between teams.
Unified API
Clients interact with a single endpoint, served by a GraphQL Gateway (sometimes called Router).
The complexity of distributed systems is hidden from the client, and the gateway ensures that every query reaches its destination.
How GraphQL Federation Works?
GraphQL Federation creates a unified API thanks to three key components: subgraphs (individual service APIs), a composition layer that validates and combines schemas, and a gateway that routes client requests across the distributed system.
Subgraphs
GraphQL federation revolutionizes API development through subgraphs - standalone GraphQL APIs that form its foundation. In a GraphQL federation architecture, each subgraph can be developed in any language or framework and deployed independently from other components, making it a powerful choice for modern applications.
Defining Subgraph Schemas
GraphQL federation enables subgraphs to contribute fields to shared types through the @key directive.
In the presented example, both subgraphs define the Product type with a shared idfield marked by @key(fields: "id"). The "products" subgraph does not own the Product type, it contributes the name and price fields. Meanwhile, the "reviews" subgraph extends this type by contributing the reviews field.
This powerful feature allows teams to evolve their portions of the schema independently while maintaining a cohesive API. When a client queries for aProduct.reviews, the federation layer automatically combines data from both subgraphs using the id as the joining key.
Comparing Federation to Monolithic GraphQL API
Unlike traditional monolithic GraphQL APIs where teams are constrained to a single codebase, language, and tech stack, GraphQL federation offers flexibility. While monolithic approaches do provide benefits through shared knowledge and easier team collaboration, they come with significant limitations that GraphQL federation specifically addresses.
The challenges of monolithic GraphQL APIs include slower development cycles due to deployment queues, and reduced reliability where a single change can impact the performance or stability of the entire API. GraphQL federation transforms these pain points by introducing a more modular approach where each team gains control over their portion of the API.
Key advantages of GraphQL federation include:
- Teams maintain complete control over their specific GraphQL API domains
- Teams choose their preferred development stack
- Each subgraph can be updated on its own schedule
- Resources can be allocated precisely where needed
By implementing GraphQL federation, organizations can break free from monolithic constraints while maintaining the benefits of a unified GraphQL API.
The Products subgraph written in Go language, allows to query for products and their details like name and price.
The Reviews subgraph written in a Java, contributes reviews to the Product type (thanks to the @key directive), making it possible to query for products and their reviews.
Schema Composition and Registry
Schema composition is the pillar of GraphQL federation, enabling you to build a unified API across multiple services. It merges subgraph schemas into a single schema, called the supergraph schema.
The Supergraph represents the complete, combined graph of all your subgraphs. It acts as a blueprint of your entire federated GraphQL API, showing how different subgraphs connect and interact. Think of the supergraph as your GraphQL API's source of truth - it defines all available types, fields, and their relationships.
What makes GraphQL federation unique is its comprehensive schema validation. The composition process analyzes every subgraph schema, verifying that all types and fields work seamlessly together. This deep analysis enables GraphQL federation to catch potential issues before they reach production, setting it apart from alternatives like Schema Stitching.
During composition in GraphQL federation, the Schema Registry validates all possible operations - queries, mutations, and subscriptions - to ensure the GraphQL gateway can properly resolve them. This proactive validation is crucial for preventing runtime errors.
The Schema Registry plays a vital role in GraphQL federation's workflow. As a centralized repository, it manages subgraph registration, schema validation, and supergraph composition. When implementing GraphQL federation, the Schema Registry becomes an essential tool for maintaining your distributed GraphQL architecture and ensuring successful composition across all subgraphs.
The public GraphQL schema that clients interact with is a combination of subgraph schemas.
GraphQL Gateway (Router)
The core promise of GraphQL federation is to have a unified API and serve data from a single endpoint. GraphQL gateway, also known as a GraphQL router, enables that.
In a federated GraphQL setup, the gateway uses a supergraph schema to retrieve information about the type and field definitions, as well as the subgraphs that resolve them.
Query Planning
The process of resolving GraphQL requests by the gateway is called query planning.
When the gateway receives a request, it:
- Analyzes the incoming GraphQL query
- Determines which subgraphs are responsible for different fields
- Orchestrates parallel requests to relevant subgraphs
- Aggregates returned data into a single response
Essential Features of a Federation Gateway
GraphQL gateway is a critical part of your federated GraphQL setup as it's the entry point for all your GraphQL clients. It has to be fast, reliable and secure.
A production-ready GraphQL gateway should offer features like authentication with JSON Web Tokens (JWT), role-based access control (RBAC), and a good observability story. It should be able to handle a large amount of requests.
Specification Compliance
A critical yet often overlooked aspect of the GraphQL gateway is its correctness and compliance with the Apollo Federation specification. The Federation's effectiveness depends on the gateway's ability to correctly resolve queries, mutations and subscriptions.
When choosing a federation gateway, verify its compliance with the Apollo Federation specification. This will help you prevent unexpected runtime behavior and data resolution failures.
At The Guild, we maintain an open-source Federation Testing Suite to verify the gateway's specification compliance. This test suite helps ensure your gateway correctly implements federation features beyond basic directive support.
The gateway resolves the query by sending parts of it to the right subgraphs.
Client receives the data from the gateway in a single response.
Why Choose Hive for GraphQL Federation?
Complete Federation Stack
- Gateway — efficiently serve data from your federated graph.
- Schema Registry — ensure consistency and compatibility across your federated graph.
- Observability — monitor supergraph performance and schema usage.
True Open Source
- No Vendor Lock-in — Every component works independently with other vendors (including Apollo GraphOS).
- MIT License — All components are available under the permissive MIT license.
- Full Control — Self-host any component or use our cloud offering.
Enterprise Tooling for GraphQL
- Single Sign-On — Integrated with popular providers like Okta, to enable OpenID Connect login for maximum security.
- Security and Compliance — Access control with role-based access control (RBAC), JSON Web Tokens (JWT) and Persisted Operations.
- Audit logs — Keep track of all the changes made to your organization.
Frequently Asked Questions About GraphQL Federation
What is the difference between schema stitching and federation in GraphQL?
Schema Stitching manually combines multiple GraphQL schemas through a gateway, requiring explicit definitions for schema merging and data fetching.
GraphQL federation, however, is an automated approach where independent services (called subgraphs) define their own schemas and resolvers, which are automatically composed into a unified schema (supergraph) by a process called schema composition, using special directives to manage cross-service references, and a gateway to route queries to the appropriate subgraphs.
What is the difference between BFF and Federation in GraphQL?
BFF (Backend-for-Frontend) creates custom backends for specific frontend clients (like mobile or web), tailoring data and logic to each client’s needs.
In contrast, GraphQL Federation composes multiple GraphQL services into a single API, allowing teams to manage parts of a schema independently while providing a unified API.
BFF focuses on client-specific optimization, while Federation is like having puzzle pieces that fit together to create one complete API.
Which companies use GraphQL Federation in production?
Many industry leaders successfully use GraphQL federation at scale. Notable examples include Netlifx, Expedia Group, Volvo, and Booking. These companies prove that Federation works reliably for large-scale production applications.
How to federate a monolithic GraphQL API?
Treat your GraphQL API as a single subgraph and use a federation gateway on top. Start decomposition process by identifying clear domain boundaries within your schema and extract them into a separate services. Start with a schema that has minimal dependencies and gradually move to other parts of the schema.
Learn how Coinbase transitioned from a monolith GraphQL API to GraphQL Federation in this conference talk.
Get Started with GraphQL Federation
Begin your journey with GraphQL Federation through our step-by-step guide, which walks you through Apollo Federation fundamentals and helps you build your first gateway and subgraphs from scratch.
Start building now