Extending your GraphQL service: Federation or Schema Stitching

If you’re looking to extend your GraphQL service into separated services, you’ve likely come across two key terms: schema stitching and federation. Even if these concepts are new to you, don’t worry—this post will introduce you to both approaches and help you understand their role in enhancing your GraphQL infrastructure.

What Is GraphQL?

Let’s start with a brief overview of GraphQL: it’s a query language and runtime for APIs that work with your existing data. GraphQL delivers precisely the data you need—no more, no less—and allows APIs to evolve over time.

However as GraphQL gained widespread adoption, many companies faced growing pains with their implementations. As their graphs grew, they began to face the challenges typical of monolithic systems. These large graphs blurred the lines between distinct business domains, which is where separating GraphQL services becomes beneficial.

There are several reasons why you might want to split your GraphQL service into smaller, separate services:

Separate Business Domains

In most applications, data is already organized by business domains. For instance, the data and logic behind a Users service are distinct from that of an Orders service. Separating your GraphQL services allows you to maintain this natural separation, making it easier to manage, develop, and scale each domain individually.

Scaling Requirements

As your GraphQL service grows, maintaining a single, monolithic system can lead to complexity and performance issues. Different parts of the system may have varying scaling needs—for example, user-related queries might need to handle more traffic than order-related ones. Splitting services by domain allows each one to scale independently based on demand, improving both performance and resource efficiency.

Simpler Ownership and Maintenance

Having distinct GraphQL schemas and resolvers for different services enables parallel development by different teams. It also simplifies ownership and accountability, as each service can be managed and maintained independently. Smaller, focused services are easier to understand, test, and deploy, making long-term maintenance less burdensome compared to a single, complex monolith.

What Is the Solution?

The solution may seem straightforward: separate the different domains and information into different schemas. But what happens when domains or information are related?

This is where schema stitching or federation comes into play. These approaches allow definitions to relate data between different schemas.

Schema Stitching

Schema stitching takes many smaller services’ schemas and stitches them together to make a larger schema. This larger schema is used by a proxy service, the gateway, to delegate different parts of the query to different subschema services.

There are three main approaches to schema stitching:

Schema Extension (Gateway-Level Configuration)

Schema extension uses schema delegation to take different subschemas and extend them at the gateway level.

Say you had a type, book and a type author in different schemas and services. At the gateway level you can extend the type book with a new field author that delegates to the author service.

Type Merging (Gateway-Level Configuration)

Type merging allows for partial definitions of a type to exist in any subschema which are all merged into a unified type at the gateway.

This is useful if you have different standalone GraphQL APIs and you need to configure those at the gateway level.

Lets consider a situation where you needed a type author but had two different services. In the first service you would have the fields id and name . In the second service you would have the fields id and description. In the gateway it would merge the author type to contain all the fields id, description, and name. When you built a query it would go to the service that declared the type.

Stitching Directives (Service Level Configuration)

Similar to Federation, schema stitching allows for directives-based approach of schema stitching. This allows you to configure your merging at the service level versus the gateway level.

In this example you would use the @merge directive and @key directive with a selectionSet to explain how to merge the schemas.

Federation

Federation lets you use directives to combine multiple APIs into a single federated graph.

When a user makes a request, it goes through the router. Based on the directives, the router orchestrates and distributes the request across the APIs and returns a unified response.

This router needs a supergraph as a map to route to the different subgraphs, this supergraph can be created by paid applications like GraphOS or free services such as The Guild’s own Hive.

Federation introduces the concept of Entities which are federated types that exist across multiple subgraphs.

Here is a comparison of Federation-Compatible Gateway Implementations:

https://the-guild.dev/graphql/hive/federation-gateway-audit

For more information on Federation and The Guild’s support, please see here:

https://the-guild.dev/graphql/hive/federation

What Is the Overall Difference?

Schema stitching merges multiple schemas into a single unified schema by directly combining them. In this setup, the gateway executes the requests by resolving data from multiple services, often relying on custom logic to determine how to fetch and combine the data from different schemas.

Federation allows each subgraph to manage part of the unified schema independently. The central gateway composes these subgraphs into a unified graph, and relationships between services are handled through federation directives like @key, @provides, and @extends. The gateway uses these directives to predetermine how data is fetched and merged across services.

This structure enables static checks, ensuring predictable behavior of the gateway in production. By using tools like Hive CLI or Apollo Studio to create the supergraph, you can validate the schema ahead of time, preventing conflicts before the supergraph is deployed. Additionally, these tools provide insight into how the gateway will execute queries, giving you confidence in its behavior after deployment.

The Guild’s products are compatible with both Federation and Schema Stitching.

Which One Is Better for Your Use Case?

This is a question only you can answer, but let’s look at common questions you should ask to determine which approach is better for your use case.

What is the overall GraphQL knowledge for the teams involved?

Federation requires more over knowledge of GraphQL from all teams involved as they need to work together to make the federated schema work as expected. Schema Stitching requires less knowledge from subschema teams but more knowledge from the team owning the gateway as the stitching logic can become complex as the number of services grow.

What is your organizational structure?

If you have teams across organizations who need to collaborate, it may be better to use Apollo Federation as it supports more collaboration on the schema so teams need to work together and understand what each other is doing with their schema.

If you want to minimize the need for teams to collaborate closely, schema stitching might be a good choice. With schema stitching, the gateway “magically” combines the services for the teams managing subschemas. The gateway handles most of the stitching process, so subschema teams don’t need to worry about how their schemas are integrated.

How fast do you need to build your solution?

Schema Stitching is usually a faster approach for smaller or simpler projects since it is straight forward. You can combine schemas quickly without much additional infrastructure but it takes longer to develop as the overall service grows.

Federation takes a bit longer to set up as it requires multiple subgraphs, a gateway, and a registry. As the services grow, Federation can speed up development for teams since each team independently manages their service.

How customizable does your implementation of the gateway need to be?

Schema stitching allows for a deeper customization of schemas, resolvers, and transformations since you have full control over how each service is combined.

Federation is more suited for scalability and team collaboration. Customization is more structured through federation directives.

If you would like to talk to an expert in regards to your GraphQL implementation, feel free to get in touch with The Guild here.