5 ways to stitch, integrate, compose & federate multiple GraphQL APIs

Editor's Note: This post focuses on the WunderGraph SDK. Our main product today is WunderGraph Cosmo , an open-source GraphQL federation platform in the same category as Apollo GraphOS. Cosmo is one implementation of the federation model: it composes subgraphs into a federated supergraph, serves it through a router, and includes schema checks and analytics. If you're evaluating federation, see the key features of WunderGraph Cosmo .

Federated GraphQL offers a structured way of joining disparate data sources and APIs under a unified graph, which can reduce integration complexity while improving collaboration across teams. SoundCloud transitioned to this federated approach using WunderGraph Cosmo — read their case study. If you're curious about their journey from traditional Backend for Frontend (BFF) patterns to a federated solution, let's chat—book a time with us!

I've seen this question come up repeatedly in community discussions: how do you integrate your own GraphQL API with a third-party (Shopify) GraphQL API?

In a nutshell, they are building their own GraphQL API and want to integrate it with Shopify's GraphQL API. What sounds like a simple task, is actually quite complex.

They seem to have some experience in the field, so they identified the biggest problem right away: When combining multiple GraphQL APIs, how do you protect certain fields for different groups of users (role-based-access) and what's the right way of injecting different credentials depending on the user and origin?

There are several methods of combining multiple GraphQL APIs. Stitching, wrapping, federation, composition, and connectors are the most common ones. We'll look at all five, how they solve the problem (or don't), and where they differ.

GraphQL Schema stitching is a technique that allows you to combine multiple GraphQL APIs into one. It allows you to combine a set of heterogeneous APIs that don't know about each other. The result is a single combined GraphQL Schema that can be queried by a single GraphQL endpoint.

What's great about this is that as a developer, you can now interact with both APIs as if they were one. Additionally, schema stitching allows you to build "link" between the two schemas. This means that you can query Products from the Shopify API, and "join" them with reviews from your own API.

While schema stitching is a great way to combine multiple GraphQL APIs, this approach also has some downsides.

First, when stitching multiple GraphQL APIs together, you might run into naming conflicts. The more APIs you combine, the more likely it is that you'll run into naming conflicts. Naming conflicts can be resolved by renaming fields or types, but this can be a tedious task. So, it's not a show-stopper, but it's something to keep in mind.

Second, schema stitching is a very manual process. If you want to add links between your schemas, you have to do this manually.

Third, authentication and authorization get more complex when combining multiple GraphQL APIs. Implementing authentication and authorization for a single API is already a complex task, but it's doable. As you own the API implementation, you can implement authentication in a way to "inject" the user object into the resolver context. Inside the resolvers, you're able to access the user object from the context and can use it to implement authorization.

But how does this work if you don't actually own the API implementation? Shopify doesn't understand your user object, and the resolver is actually a "remote-resolver".

Now imagine that, depending on the role of the current user, you want to allow them to use certain fields on the Shopify API, while regular users should not be able to access those fields. Additionally, you need to inject different credentials depending on the user and origin.

This is where schema stitching gets really complicated. It's doable, by adding custom middlewares to intercept the requests and rewrite them, but it definitely shows the limits of schema stitching. We'll look at federation and schema composition later to see how they can solve this problem, better or worse.

Finally, schema stitching comes with another "downside": Schema design, or the opposite.

When you build a single GraphQL API, this API (hopefully) follows certain design principles. The way you name your fields, types and arguments should be consistent. When you look at the Schema, you can clearly see that it's one single API.

Once you start stitching multiple GraphQL APIs together, you end up with an API that follows multiple design principles. There are many ways how GraphQL Schemas can differ from each other, like camel case vs snake case, plural vs singular for field names, input objects vs long lists of arguments, unions for responses to indicate known errors vs error codes in the error object and flat response objects.

If you're using GraphQL as an "internal API ORM", this is fine. However, if you're exposing the GraphQL API to other teams or even the public, you might want to consider a better option than exposing your Frankenstein-stitched-API to the world.

In contrast to schema stitching, schema wrapping doesn't really combine multiple GraphQL APIs side-by-side. Instead, you're wrapping all 3rd party APIs under a single umbrella-API.

The main benefit of schema wrapping is that you have full control over the API design and implementation. You can safely wrap the Shopify API without leaking any implementation details to the outside world. As you're the full owner of this API, you can implement authentication and authorization in a way that fits your needs.

Full control and power over the API design and implementation is great, but this comes at a cost.

Schema stitching has some manual parts, but a lot of the work is done automatically. With schema wrapping, you have to do everything manually. This means, you have to write all resolvers, all middlewares and all the glue code yourself. Additionally, you have to maintain the API implementation yourself. If you're using a 3rd party API, you have to make sure that you're always up-to-date with the latest changes.

In terms of performance, schema wrapping typically runs through two layers of resolvers. This can have a negative impact on performance. A single GraphQL API might be able to solve the N+1 problem using the dataloader-pattern. But when you're wrapping multiple GraphQL APIs, you might end up with inefficient execution plans where the dataloader-pattern doesn't work anymore.

An example is when you fetch the current shopping cart from your own API, and want to fetch the current price of the products from the Shopify API. You'll end up making multiple requests for the nested price field. This nested field is not part of the "local" API, so the dataloader-pattern won't work here.

Another option is GraphQL Federation — a specification (originated by Apollo and now implemented by multiple platforms) for composing multiple subgraphs into one supergraph and routing requests across them. Compared to schema stitching, federation is a more declarative approach.

The goal of federation is to design a single GraphQL API that can be implemented by multiple services. Each service can be implemented by a different team, and each service can be implemented in a different programming language. But all services together form a single GraphQL API.

Two of the more widely discussed platforms today are Apollo GraphOS (source-available, ELv2) and WunderGraph Cosmo (open source, Apache 2.0). Other open-source routers and registries exist as well — Hive from The Guild provides a registry-and-checks layer for teams on The Guild's router stack, among others. For an overview of the open-source landscape, see A Brief Overview of Open Source GraphQL Federation.

Cosmo composes subgraphs with the wgc CLI, runs schema checks in CI, and serves the unified graph through the Cosmo Router. If you're evaluating platforms, Cosmo vs Apollo GraphOS lays out the tradeoffs. For how the pieces fit together, see the Cosmo architecture docs .

The main benefit over schema stitching is that federation can encourage a more consistent API design when you treat the supergraph as the contract and enforce schema review across teams. Federation allows you to scale a landscape of GraphQL services across multiple teams — with composition checks that catch breaking changes before they reach production.

That said, federation alone doesn't solve the problem of merging arbitrary third-party GraphQL APIs. While it's a strong fit when a single organization controls the subgraphs, it's usually not the most practical option when you need to integrate APIs you don't own or operate.

Shopify will most likely not respect your API design guidelines. Imagine you'd have to achieve consistent API design across all companies who expose their APIs publicly. It's not really feasible.

So, while federation is a strong fit for internal services you control, it doesn't directly solve the third-party GraphQL integration problem — that's where connectors and composition come in.

Note: The code below uses the original WunderGraph SDK. The current product, Cosmo, takes a different approach to composition. See Cosmo schema composition.

So far, we've discussed the tradeoffs between the two possible approaches, schema stitching and schema wrapping, while we've dismissed federation as it solves a different problem.

Schema wrapping, being the most expensive one to implement, is really only an option if you have to expose the API to the public. At the same time, schema stitching still clocks in relatively high in terms of complexity and maintenance.

That's where schema composition comes in handy. Schema composition embraces the idea of treating APIs as dependencies. Naming conflicts are resolved using namespacing, allowing us to combine multiple APIs fully automatically.

The way we've implemented schema composition at WunderGraph is that we're not actually exposing the composed GraphQL API. Instead, we're using GraphQL Operations as a tool to define our actual API, a REST / JSON-RPC API. GraphQL is simply the language to manage the (API) dependencies, but the resulting API is not a GraphQL API.

That's why we call the resulting Schema the "Virtual Graph". It's virtual, because it only really exists during development.

Here's an example of how a GraphQL Operation in a composed virtual graph looks like:

The resulting JSON-HTTP API creates an endpoint that returns the country data including weather for a given continent.

The main benefit is that you can declaratively compose multiple APIs and treat them as dependencies, without hand-stitching every field or resolver. The caller of the API doesn't even have to know that the API is composed of multiple APIs.

This means, we're able to expose the JSON-HTTP API as one single API. Authentication and Authorization across all APIs can be handled in a single place.

If some APIs should only be accessible to special users, like admins, you can apply role-based-access at the API Gateway level. Additionally, you can handle injecting credentials, like admin or super admin tokens from within the API composition layer. API Composition is designed for exactly this use case.

For each origin, different rules might apply on how to authenticate against the API. If we're treating APIs as dependencies, we can implicitly handle authentication and authorization for each API.

The main downside of this approach is that we're not exposing a GraphQL API. Instead, we're exposing a JSON-HTTP API.

However, I've found that this is actually more of a benefit than a downside. When deploying a GraphQL API to production, you're very unlikely to change the GraphQL Operations at runtime. So, if we're not changing the Operations, we don't really need to expose a dynamic API. We can simply expose a fixed set of GraphQL Operations in the form of a JSON-HTTP API.

More and more tools emerge to "secure" GraphQL APIs. By exposing a fixed JSON-HTTP API instead of a fully introspectable GraphQL endpoint, you remove many of the concerns specific to open GraphQL schemas — though you still need to handle standard API security practices like authentication, authorization, rate limiting, and input validation.

The real downside of this approach is that it doesn't work if your intention is to expose the API to the public. While most GraphQL APIs are used internally, if your use case is to expose the API to the public, you're better off using schema wrapping.

As described above, composition treats APIs as dependencies, so adding another API tends to have constant local complexity, whereas naive stitching can trend toward quadratic complexity as you manage pairwise links and naming collisions.

This means you can add APIs to a composed graph without the same combinatorial overhead that stitching often introduces. The more APIs you combine with schema stitching, the more edge cases, like naming collisions, you'll have to deal with.

Here's an example of how to compose two APIs:

Simply make sure that you're using different namespaces for each API. That's the power of thinking in "APIs as dependencies".

A fifth approach has emerged as federation platforms matured: connectors — declarative bindings that attach federated schema fields to REST, gRPC, or OpenAPI backends without deploying separate subgraph services.

Cosmo Connect is WunderGraph's take. Instead of declarative directives, you define an Apollo-compatible subgraph schema and map it to gRPC contracts implemented as router plugins or standalone gRPC services. Backend teams still implement the logic behind those contracts — the connector layer is glue, not a complete solution on its own — but clients get one unified graph without every team running a GraphQL server.

Connectors are particularly useful for legacy systems and third-party APIs you don't control, and are usually more complementary than foundational for greenfield architectures — subgraphs with proper entity resolvers typically handle batching and N+1 better. For the full tradeoff analysis, see Are Connectors the path forward for GraphQL Federation? and Cosmo Connect vs Apollo Federation vs GraphQL Federation.

To get started, follow the Cosmo Connect tutorials .

One additional benefit of Schema Composition is that you can use it together with Schema Stitching and Federation. You're not forced to using one pattern exclusively. A common hybrid pattern: use federation for internal subgraphs you control, composition for third-party or heterogeneous APIs, and stitching only for small or legacy cases where the overhead of a full platform isn't justified. Why not build internal GraphQL services with federation and use schema composition to join third-party APIs on top? It can combine the strengths of both approaches — though the operational complexity of running multiple integration patterns is real, and worth budgeting for upfront.

Now that we've discussed the different approaches, let's summarize when to use which approach.

Schema wrapping is the most expensive solution to implement, but it's also the most flexible one.

Wrapping 3rd party APIs is the right way to go when you want to expose the API to the public and don't want to expose the underlying APIs.

Schema Stitching allows you to combine multiple heterogeneous APIs in a semi-automatic way. It doesn't scale well in terms of number of APIs, but if it's a small number, it might work. Keep in mind that the resulting API doesn't follow a single set of design principles.

GraphQL Federation is a strong fit for composing schemas and routing requests across services — whether your teams follow strict microservices or more coarse-grained service boundaries. Federation is most effective when a single organization controls the subgraphs and can enforce shared contracts and review processes. Use Cosmo, Apollo GraphOS, or another federation platform depending on your licensing and hosting requirements.

For integrating arbitrary third-party GraphQL APIs that you don't control, federation alone is usually not the most practical approach.

Connectors are often a good fit when you need REST, gRPC, or other non-GraphQL services on a federated graph without rewriting them as GraphQL subgraphs. They're especially useful for legacy systems and third-party APIs you don't control.

Pair connectors with federation for internal subgraphs and connectors for everything else — see Cosmo Connect for the implementation path.

Schema Composition or thinking in "APIs as dependencies" is the right approach when you need to compose a large number of APIs and want to expose the "API Composition" as a single API.

Schema Composition can be used together with Schema Stitching and Federation, letting you mix patterns where each one fits best.

In this article, we've discussed five approaches to combine multiple GraphQL APIs: stitching, wrapping, federation, composition, and connectors. Depending on your requirements, you might use one exclusively or combine several.

If you're interested in federation with Cosmo today, see the local development tutorial , the Open Source GraphQL Federation overview, and Cosmo Connect for bringing REST and gRPC services onto the graph.

WunderGraph Cosmo is an open-source platform for running federated GraphQL in production. Get started with Cosmo or book a call .

Frequently Asked Questions (FAQ)