Published: 7 February 2024
Contributors: Chrystal R. China, Michael Goodwin
GraphQL federation is a distributed architectural approach that enables developers to use a single API across multiple GraphQL services (that is, services that are written in the open-source query language, GraphQL).
Federation divides schema—the contract between back-end and front-end operations—into more manageable components and microservices, allowing teams to build, deploy and manage portions of a schema independently, while maintaining a unified data graph for clients to interact with.
In a federated GraphQL environment, a GraphQL gateway integrates multiple schemas—also called subgraphs or services—into a single graph (or router). Each subgraph defines part of the overall schema and handles the business logic and data retrieval for its own types and fields. The gateway then stitches stand-alone subgraphs together into a supergraph, allowing clients to query data sources across services as if interacting with a single GraphQL schema.
Learn how to break down data silos with highly responsive GraphQL APIs.
IBM API Connect wins top distinctions
Before federation, one of the primary methods for combining multiple GraphQL schemas was schema stitching, where different schemas and resolvers are combined manually. It required developers to define how the schemas are merged and how data would be stitched together. And while schema stitching did offer a unifying solution for GraphQL schema, it was also complex and error-prone, making it difficult to manage.
To address these issues and streamline schema stitching processes, the engineers behind Apollo—a GraphQL implementation for product and app engineering—developed Apollo federation. Apollo federation introduced “key,” “external,” “requires” and “extends” keywords to define the connections between types in different services. The new cross-referencing features enabled developers to use an Apollo gateway to build a cohesive data graph without relying on an overly complex stitching logic.
However, Apollo GraphQL federation wasn’t just a new set of tools and libraries. It was also a system specification that described the architecture and how services can communicate to form a distributed graph. This enabled other implementations and tools to adopt federation principles and helped establish a standard for building federated GraphQL APIs.
Since its introduction, GraphQL federation has undergone numerous improvements. Managed federation, for instance, can facilitate metrics collection and enable automatic gateway updates when subgraphs change, all without manual intervention or system downtime.
Advancements also include the development of Federation 21, an innovation that simplified cross-service schema merging and query execution, increased modularity for greater control over schema composition, and improved error visibility for easier tracking and debugging.
Apollo federation represented a significant advancement for building streamlined API ecosystems, and it remains an option for businesses that are looking to deploy federated IT architectures.
Still, an Apollo-based federation approach locks developers into a single-vendor implementation, as Apollo-federated environments can accept only Apollo-defined directives and types from Apollo or Apollo-compliant backend technologies. In other words, Apollo federation often limits system flexibility, even as new technologies emerge.
Developers who are seeking to optimize flexibility while keeping the unified-layer functionality of Apollo federation might prefer open federation. Open federation approaches enable systems to combine data from any API vendor or type, including non-GraphQL APIs. Using tools like IBM API Connect, businesses can customize and scale their IT assets without compatibility restrictions and continue to adopt innovations from a range of tech communities.
GraphQL helps clients request exactly the data that they need without under- or over-provisioning resources, making it a great option for businesses that are looking to optimize operational efficiency.
Given its flexibility, it’s no surprise that GraphQL is an increasingly popular query language and runtime for APIs.2 However, as web and mobile apps become more sophisticated, deploying a single, monolithic GraphQL server (and all its dependencies) can become untenable. Federation simplifies GraphQL ecosystems by helping disparate subgraphs work together as one cohesive GraphQL service.
Implementing a federated GraphQL architecture involves the following key processes.
Defining subgraph schemas involves identifying domain boundaries and deciding how those boundaries should interact.
In a federated architecture, each subgraph schema represents a specific portion of the overall data graph; it contains types, configs, queries, mutations and subscriptions that apply to a service or domain. A product service, for example, might have a subgraph schema that includes types like product and review, while a user service might have user and profile types.
Subgraph schemas are defined in much the same way as a standard GraphQL schema but with the addition of federation-specific directives. Federation directives provide instructions for how a system extends entities across schemas and how the gateway should resolve specific fields across services. They also define keys for referencing entities.
As one example, the @key directive specifies the fields that identify a type across federated graphs; when deployed, this directive prompts the gateway to retrieve an entity from the service that owns the specified type. The @extends directive indicates that a type defined in one subgraph schema extends a type that originates in another, facilitating type extension (with additional fields) in another service.
Subgraph services are back-end services that implement the business logic for corresponding subgraph APIs. Each subgraph service defines its piece of the data graph and handles queries and mutations related to its domain. Their respective resolvers fetch any associated data from the appropriate data sources, databases or REST APIs.
Subgraph services also reveal their GraphQL endpoints to the federation gateway, which uses them to compose the overall federated schema. Keep in mind that these services can be written in any programming language, assuming the language supports GraphQL.
Federation gateways orchestrate schema composition and query planning. With the help of federation servers, gateways disguise individual subgraph services, presenting a unified API to the client.
To configure a federation gateway, teams typically specify the location of each subgraph service and set up the infrastructure necessary for schema fetching, query planning, execution and error handling. When in place, the gateway will continually fetch the schemas from subgraph services to ensure that it has the most recent version of the federated schema.
When subgraph services and the federation gateway are configured, administrators then deploy the entire system. This includes provisioning hardware and cloud resources, setting up deployment pipelines, monitoring system performance and ensuring high resource availability.
It should come as no surprise that consistent real-time monitoring is vital to optimizing a federated GraphQL environment. Vigilant monitoring enables teams to detect and resolve performance bottlenecks, system errors and unplanned downtime before they create larger issues. Monitoring also enables health tracking for subgraph services and the federation gateway.
GraphQL federation represents a significant advancement in the development of GraphQL APIs for large-scale, distributed systems. It enables teams to work on different parts of a GraphQL schema independently while seamlessly integrating their work into a unified API, all without disrupting the end-user experience.
GraphQL federation also has a wide range of use cases—from microservice architecture deployment and caching to product development and operations insights—and has been adopted by companies like Netflix, Airbnb, GitHub and Expedia.
GraphQL federation also facilitates:
In a federated environment, developers can spread the responsibility for specific data domains across multiple services, allowing them to orchestrate and scale individual services (and their functions) more nimbly.
Because federated services can be managed independently, team members can work on their respective domains without interfering with one another.
Unlike REST API environments, GraphQL federation allows clients to fetch all the resources and data they need with a single request, eliminating redundancies and optimizing resource deployment.
IBM API Connect is a full lifecycle API management solution that uses an intuitive experience to help consistently create, manage, secure, socialize and monetize APIs, helping power digital transformation on premises and across clouds.
IBM API Connect enables the building and deployment of a production-level GraphQL API in minutes. Simply provide the connection details of your data source and a secure and optimized GraphQL API will be generated instantly.
Learn about the two different approaches these frameworks take for building APIs and the strengths and weaknesses of each.
Find out why IBM continues to be recognized as a Leader in API Management.
Explore the IBM API Connect toolkit.
Maximize API value to drive digital business with a comprehensive API management solution.
Find out why IBM was named a Leader in the 2023 Gartner Report: Critical Capabilities for API Management.
These tutorials provide hands-on instructions that help developers learn how to use the technologies in their projects.
Footnotes
1 Apollo GraphQL Introduces Federation 2 to Get More Organizations to the Graph (link resides outside ibm.com), BusinessWire, 03 November 2021.
2 Why GraphQL Needs an Open Federation Approach (link resides outside ibm.com), The New Stack, 16 November 2023.