Schema Stitching Basics: Combining Multiple GraphQL Services

Previously in this course, we explored Organizing Schema Files: Modularizing GraphQL Type Definitions to keep our local code maintainable. While that approach helps manage a single project, schema stitching takes this concept to a larger scale by combining completely independent GraphQL services into one unified gateway.

What is Schema Stitching?

Schema stitching is a technique where you take two or more separate GraphQL services and merge them into a single, coherent schema. From the client's perspective, it looks like they are querying one massive API, but behind the scenes, the gateway orchestrates requests to different underlying servers.

Think of it like a "front-door" server. When a request arrives, the gateway inspects the query, breaks it down into parts, sends those parts to the appropriate sub-services, and merges the results back together before returning the final JSON response to the user.

Why Stitch Schemas?

In a growing organization, you might have one team working on a "Users" service and another on an "Orders" service. Each team manages their own database and their own GraphQL server. Schema stitching allows you to expose these as a single graph without forcing both teams to maintain a massive, shared codebase.

Implementation Concept

To stitch schemas, your gateway server needs two things: the schema definitions (SDL) from your sub-services and the ability to execute requests against them.

While older implementations required manually stitching types, modern GraphQL gateway libraries (like those provided by the Apollo ecosystem) allow you to define "links" between types across services. For example, you might add a user field to an Order type that lives in the Orders service, effectively "stitching" it to the User type in the Users service.

A Concrete Example

Imagine your Order type only has a userId. You want to fetch the actual User object directly within an order query.

GraphQL
# The Order service SDL
type Order {
  id: ID!
  amount: Float!
  userId: ID!
}

# The User service SDL
type User {
  id: ID!
  name: String!
}

By stitching these, you can extend the Order type in your gateway:

GraphQL
extend type Order {
  user: User @merge(keyField: "userId")
}

The gateway now knows that whenever a client asks for user on an Order, it should take the userId from the order and query the Users service.

Pros and Cons

Pros:

• Scalability: You can split your domain into microservices as the organization grows.
• Separation of Concerns: Different teams can own different parts of the graph.
• Gradual Adoption: You can start with a monolith and stitch in new services as you build them.

Cons:

• Gateway Complexity: The gateway becomes a critical point of failure and adds latency.
• Performance: Naive stitching can lead to "N+1" problems across network boundaries if not managed with proper batching.
• "Federation" is often better: Modern tooling (like Apollo Federation) is built to solve these problems more robustly than manual stitching.

Hands-on Exercise

1. Identify two distinct domain models in your current project (e.g., Product and Review).
2. Sketch out how you would represent them if they lived on two different servers.
3. Define the "join key" that links them together (e.g., productId in the Review object).
4. Consider: If your project were to grow, what is the biggest challenge you would face by splitting these into two separate services?

Common Pitfalls

• Circular Dependencies: Trying to stitch Service A to Service B, while Service B also depends on Service A, can lead to infinite request loops if you aren't careful.
• Ignoring Latency: Every "stitch" is a network request. If your gateway has to hit three different services to resolve a single query, your response time will be the sum of all those network round-trips.
• Schema Drift: If the underlying service changes a field name, the gateway might break without warning. Always use a registry or schema versioning to keep these in sync.

FAQ

Is schema stitching the same as federation? They are related but different. Schema stitching is the manual, more flexible "stitching" of schemas. Federation is a more opinionated, automated approach that uses specific directives to handle the merging of types, which is currently the industry standard.

Do I need this for my project right now? No. If you are just starting out, keep your schema modular as we did in Organizing Schema Files: Modularizing GraphQL Type Definitions. Only move to stitching or federation when your single server becomes too large for one team to deploy safely.

Recap

We've covered the basics of schema stitching, an architectural pattern for composing a unified graph from multiple independent services. While it provides immense benefits for team autonomy and scaling, it introduces network overhead and complexity that should be reserved for larger-scale applications.

Up next: We will shift gears to testing, where you'll learn how to write automated test cases for your GraphQL queries using Jest.