Gateway composition in GraphQL - Deep Dive

Overview - Gateway composition

What is it?

Gateway composition is a way to combine multiple GraphQL services into one single API. It lets clients ask for data from many sources through one gateway, which merges the results. This makes it easier to manage and scale complex systems with many data providers.

Why it matters

Without gateway composition, clients would need to call many different APIs separately, making apps slower and harder to build. Gateway composition solves this by giving a unified, simple interface that hides the complexity of multiple services. This improves developer productivity and user experience.

Where it fits

Before learning gateway composition, you should understand basic GraphQL queries and schemas. After this, you can explore advanced topics like schema stitching, federation, and performance optimization in distributed GraphQL systems.

Mental Model

Core Idea

Gateway composition merges multiple GraphQL services into one API that answers client queries by delegating parts to each service and combining their responses.

Think of it like...

Imagine a restaurant waiter who takes your order and then asks different kitchen stations to prepare parts of your meal. The waiter then brings all the dishes together to serve you as one complete meal.

┌─────────────┐
│   Client    │
└──────┬──────┘
       │ Single query
       ▼
┌─────────────┐
│   Gateway   │
│ Composition │
└──────┬──────┘
       │ Splits query
       ▼
┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│ Service A   │   │ Service B   │   │ Service C   │
└─────────────┘   └─────────────┘   └─────────────┘
       │               │               │
       └─────Results combined───────┘
                 │
                 ▼
           Unified response

Build-Up - 7 Steps

1

Foundation

Understanding GraphQL basics

Concept: Learn what GraphQL is and how queries and schemas work.

GraphQL is a way to ask for exactly the data you want from a server. You write queries that specify fields and nested data. The server has a schema that defines what data is available and how it is structured.

Result

You can write simple queries to get data like a user's name or a list of posts.

Understanding GraphQL basics is essential because gateway composition builds on how queries and schemas work.

2

Foundation

What is a GraphQL service?

Concept: A GraphQL service is a server that understands GraphQL queries and returns data according to its schema.

Each service owns a part of the data and schema. For example, one service might handle user data, another handles products. Each service runs independently and responds to queries about its data.

Result

You can query each service separately and get data from that domain.

Knowing what a GraphQL service is helps you see why combining them is useful.

3

Intermediate

Why combine multiple GraphQL services?

🤔Before reading on: do you think clients can easily query multiple services directly or is a single combined API better? Commit to your answer.

Concept: Combining services into one API simplifies client queries and hides complexity.

If clients had to call many services separately, they would write more code and handle more network calls. Gateway composition lets clients send one query to one endpoint, and the gateway splits it to the right services.

Result

Clients get a unified response without managing multiple requests.

Understanding the client benefit clarifies why gateway composition is a key pattern.

4

Intermediate

How gateway composition works

🤔Before reading on: do you think the gateway merges schemas before or after receiving queries? Commit to your answer.

Concept: The gateway merges schemas from services into one combined schema and delegates query parts to each service.

The gateway builds a single schema by combining the schemas of all services. When a client sends a query, the gateway breaks it into subqueries for each service, sends them, and merges the results into one response.

Result

The client sees one schema and one response, even though multiple services are involved.

Knowing the gateway's role in schema merging and query delegation is key to understanding composition.

5

Intermediate

Schema merging challenges

🤔Before reading on: do you think two services can have overlapping types without problems? Commit to your answer.

Concept: Merging schemas can be tricky when services have overlapping or related types.

If two services define the same type differently, the gateway must resolve conflicts. Also, linking related types across services requires special handling to allow queries that span services.

Result

Proper schema composition enables seamless cross-service queries.

Understanding schema conflicts and type linking helps avoid errors in gateway composition.

6

Advanced

Apollo Federation as gateway composition

🤔Before reading on: do you think federation requires changing service schemas or just the gateway? Commit to your answer.

Concept: Apollo Federation is a popular way to implement gateway composition by extending service schemas with special directives.

Federation lets services declare how their types extend or link to others using @key and @extends directives. The gateway uses this metadata to compose schemas and resolve queries across services.

Result

You get a powerful, scalable gateway that supports complex data relationships.

Knowing federation's approach reveals how real-world systems solve composition challenges.

7

Expert

Performance and caching in gateway composition

🤔Before reading on: do you think the gateway caches entire responses or parts of queries? Commit to your answer.

Concept: Optimizing performance involves caching and batching requests at the gateway level.

Gateways can cache parts of query results to reduce load on services. They also batch multiple subqueries to the same service to minimize network calls. These optimizations improve response times and scalability.

Result

Gateway composition can handle high traffic efficiently without slowing down clients.

Understanding performance techniques is crucial for building production-ready gateways.

Under the Hood

The gateway first fetches schemas from each service and merges them into one combined schema. When a client query arrives, the gateway parses it and splits it into subqueries targeting each service based on the schema. It sends these subqueries asynchronously, waits for responses, and then merges the data into a single JSON response matching the combined schema. Internally, it uses schema directives or metadata to resolve type extensions and references across services.

Why designed this way?

Gateway composition was designed to solve the problem of scaling GraphQL APIs across multiple teams and data sources. Instead of building one huge monolithic schema, teams can own separate services. The gateway merges them dynamically, allowing independent development and deployment. Alternatives like schema stitching were less flexible and harder to maintain, so federation and composition became preferred.

┌───────────────┐
│  Gateway      │
│  Composition  │
│  Engine       │
├───────────────┤
│ Fetch schemas │
│ Merge schemas │
│ Parse query   │
│ Split query   │
│ Send subquery │
│ Merge results │
└───────┬───────┘
        │
┌───────┴─────────────┐
│  Multiple Services   │
│  ┌───────────────┐  │
│  │ Service A     │  │
│  │ Service B     │  │
│  │ Service C     │  │
│  └───────────────┘  │
└─────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does gateway composition mean the gateway stores all data itself? Commit yes or no.

Common Belief: The gateway stores and manages all data centrally after composition.

Reality: The gateway only merges schemas and delegates queries; it does not store data itself.

Why it matters: Thinking the gateway stores data leads to confusion about data ownership and can cause wrong assumptions about data freshness and consistency.

Quick: Can two services define the same type independently without issues? Commit yes or no.

Common Belief: Services can define overlapping types without coordination, and the gateway will handle it automatically.

Reality: Overlapping types require explicit coordination and directives to avoid conflicts during schema merging.

Why it matters: Ignoring this causes schema conflicts and runtime errors, breaking the API for clients.

Quick: Does gateway composition always improve performance? Commit yes or no.

Common Belief: Gateway composition always makes queries faster by combining services.

Reality: Gateway composition can add overhead due to query splitting and network calls, so performance depends on implementation and optimization.

Why it matters: Assuming automatic speedup can lead to neglecting necessary caching and batching optimizations.

Quick: Is gateway composition the same as schema stitching? Commit yes or no.

Common Belief: Gateway composition and schema stitching are identical concepts.

Reality: Gateway composition, especially federation, is a more modern, flexible approach than legacy schema stitching.

Why it matters: Confusing them can cause using outdated patterns that are harder to maintain and scale.

Expert Zone

1

The gateway must carefully handle error propagation from multiple services to provide meaningful client errors without leaking internal details.

2

Extending types across services requires precise key fields and directives to maintain data consistency and avoid duplication.

3

Performance tuning often involves balancing query complexity, caching granularity, and network overhead, which varies by use case.

When NOT to use

Gateway composition is not ideal for very simple APIs or when services are tightly coupled and deployed together. In such cases, a monolithic GraphQL server or direct service calls may be simpler and more efficient.

Production Patterns

In production, teams use Apollo Federation with service-specific schemas and shared directives. They implement caching layers at the gateway, monitor query complexity, and use schema validation tools to prevent breaking changes.

Connections

Microservices architecture

Gateway composition builds on microservices by providing a unified API layer over distributed services.

Understanding microservices helps grasp why gateway composition is needed to unify diverse data sources.

API Gateway pattern

Gateway composition is a specialized form of the API Gateway pattern tailored for GraphQL APIs.

Knowing API Gateway concepts clarifies how the gateway manages routing, aggregation, and security.

Database view

Gateway composition is like a database view that combines multiple tables into one virtual table for simpler queries.

Seeing gateway composition as a virtual view helps understand how it abstracts multiple data sources into one schema.

Common Pitfalls

#1 Trying to merge schemas without coordinating overlapping types.

Wrong approach:

const mergedSchema = mergeSchemas({ schemas: [serviceASchema, serviceBSchema] }); // no conflict resolution

Correct approach:

Use federation directives or schema stitching with type extensions to resolve overlaps explicitly.

Root cause:

Misunderstanding that schemas must be compatible and coordinated before merging.

#2 Sending client queries directly to services instead of through the gateway.

Wrong approach:

Client sends separate queries to each service endpoint manually.

Correct approach:

Client sends one query to the gateway, which delegates subqueries to services.

Root cause:

Not realizing the gateway's role in simplifying client interactions.

#3 Ignoring performance optimizations like caching and batching at the gateway.

Wrong approach:

Gateway forwards every subquery immediately without caching or batching.

Correct approach:

Implement caching layers and batch requests to services to reduce latency and load.

Root cause:

Assuming gateway composition automatically improves performance without tuning.

Key Takeaways

Gateway composition merges multiple GraphQL services into one unified API, simplifying client queries.

The gateway merges schemas and delegates query parts to the right services, then combines results.

Proper schema coordination is essential to avoid conflicts and enable cross-service queries.

Apollo Federation is a modern, popular approach to implement gateway composition with schema directives.

Performance optimization at the gateway, like caching and batching, is crucial for scalable production systems.