Extending your GraphQL service: Federation or Schema Stitching

This article was published on Monday, November 18, 2024 by Emily Goodwin @ The Guild Blog

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.