Apollo GraphQL Federation with Subscriptions - production grade and highly scalable - WunderGraph

State of Federation 2026Share your insights on GraphQL Federation.Take the Survey→

Jens Neuse

CEO & Co-Founder at WunderGraph

June 11, 2021·15min read

Edited on July 9, 2026 by Brendan Bondurant

Editor's Note

This post was written in 2021 and describes an earlier version of WunderGraph that is no longer available. The product is now WunderGraph Cosmo. For current documentation on federated subscriptions, see the Cosmo Router subscriptions docs.

TL;DR

Federation and subscriptions used to be hard to run together, and in 2021 few gateways supported both. That has changed. With WunderGraph Cosmo, real-time subscriptions are built into the Router, and the modern approach is Cosmo Streams (event-driven federated subscriptions, or EDFS): the Router subscribes to an event source like Kafka, NATS, or Redis, and your subgraphs stay HTTP-only and stateless instead of holding WebSocket connections. This post keeps the still-useful parts on what Federation solves and how to adopt it, and updates the subscriptions architecture to how Cosmo does it today. The 2021 WunderNode design later in the post is kept for history.

What problems does Apollo GraphQL Federation solve?

GraphQL has proven countless times that it's helping companies build better APIs. Developers struggle to find consensus on how they should build their REST APIs. With GraphQL, despite being a compromise, developers are able to rely on a simple and clear specification that doesn't leave room for interpretation. GraphQL might not always be the best choice. However, in many cases it's easier to build a good GraphQL API compared to REST because devs have to make fewer choices.

Alright, enough GraphQL "hype". You've probably heard pro arguments on GraphQL enough. To give it some balance. No API style is a one size fits all. Depending on you use-case, you should always consider alternatives like REST, OpenAPI, gRPC etc., make yourself familiar with pros and cons of each implementation and decide for the best tool for you project. Deciding on tooling before the resulting architecture is not making your project more successful.

GraphQL itself is just a query language, paired with HTTP, you could put it in the same basked with other API styles like e.g. REST, gRPC, SOAP, etc... All of them have their pros and cons, but the patterns are quite similar.

However, when Federation comes into play, it's clear that we're operating at a completely different level. It's no longer just another API style. Federation goes beyond just architecture. Federation enables organizations to scale in a way that was not possible with other API styles.

Most if not all API styles have some kind of concept of a "Resource". I'm borrowing the term from REST APIs as it makes most sense in this context. What all these API styles have in common is that a Resource is usually tied to one Endpoint, Instance or Service.

With Federation, the implementation of a Resource can be distributed across many teams.

Imagine you have the type User in your domain model. Let's say Users are able to write Posts as well as add Comments to Posts.

If it's a simple Rails app, ofc there's no issue implementing this design. What if your application is scaling to the point where Posts and Comments are becoming large complex topics, and you have to build individual teams for each of them?

How can you make sure that the API scales well and is still as easy to use and understand as having a single monolith? This is the kind of problems that Federation tries to solve. It gives both teams to collaborate on finding a common API schema while allowing them to implement their part of the schema the way they want.

This comes with some benefits but also has a cost obviously.

Why you should use Apollo GraphQL Federation

Are you trying to scale your organization? Do you find yourself in a similar position to the example above? Do you have to split teams and hire more people because your API surface it getting bigger and bigger?

If you can answer these questions with Yes, you should definitely take a closer look!

Apollo GraphQL Federation can help you in this case to build a coherent API surface. Thanks to Federation, API consumers won't notice when they cross the boundaries of individual teams. As all teams agree on a common schema, it's easy to navigate the different types as they all follow a common language.

At the same time, teams of API producers are free to implement their part of the schema the way they want. They can use any language or framework they like, as long as the result is a Federation compliant service.

That said, it might still be a very good idea to not give each team too much freedom in terms of technology choice. If the stack is similar across teams, it's easier for team members to move between teams.

Why you should avoid Apollo GraphQL Federation

Adopting Apollo GraphQL Federation comes at a cost and is not for everyone.

Looking at the questions above, if you're mostly answering them with "No", it very likely that you don't have the problems that Federation tries to solve.

If your API surface is small, and you only have a single team of three developers working on the API, Federation adds just complexity without doing you any good.

Another situation where you have to carefully think about adopting Federation is when your company is not yet using GraphQL at all. In order to be able to leverage Federation, all services have to be rewritten as GraphQL services. This can take a huge effort, and it'll take long until the investment pays off.

Actually, with WunderGraph you don't have to rewrite all your services as GraphQL APIs but we'll come to that later.

Another important factor when it comes to adopting Federation is when you have API consumers that are not familiar with GraphQL. Rewriting your Services as GraphQL APIs means, you have to teach your API consumers a new technology. If your API consumers are mainly in-house, this might work. What if your API is used by partners or even public API consumers who are unknown to you? Can you convince all of them to adopt GraphQL? If not, you could have to build a REST-ful facade on top of your federated GraphQL API.

In the end, an API is like a product, and your customers are developers. What matters most is that you deliver a great product to your customers. GraphQL might be a solution and so does Federation. Your customers might not care about your technology choices.

How can you safely adopt Apollo GraphQL Federation?

Migrating from non-GraphQL to Federation

In case you don't already have any GraphQL APIs, the transition is a multi-step process. You can keep your existing architecture running while you start to "strangle" (wrap) it with GraphQL services. Once the first bit of your new facade is running, you can ask your API consumers to migrate to the new GraphQL API. This allows you to test your Federation environment and identify problems.

In case of issues, you're always able to switch your API consumers back to the "old" APIs. This way, you're able to build up confidence that your new architecture works under real life conditions.

You'll then migrate more and more services to the new architecture until the whole "old" API is eaten up by Federated services. At this point, you're able to migrate API consumers completely off of the "old" API.

Once this step is complete, you're able to move all business logic from the "old" API into the federated services. When no federation service and API consumer is relying on a part of the "old" API, it's time to finally switch this service off. Iterate through all the services until nobody is relying on the "old" API anymore. You can and should ensure this by looking at your API analytics.

Speaking of API analytics. It really helps if your "old" API has analytics enabled. Additionally, you should give all API consumers some information like a client ID or token by which they always have to present when using your API and by which you can identify them. If you don't have such information it can become hard to identify some of your API consumers and help them migrate off of your old API. A very good practice is to make use of OAuth2. This allows you to create a client ID and secret for all your API consumers. Each app and each partner can have their own client ID, making it easy for you to track them down. Keep a list of client IDs and their contact info and you're well-prepared for the upcoming migration.

Migrating existing GraphQL services towards a federated architecture

Assuming that you have one or more existing GraphQL services, it's very likely that it's either a monolithic service or multiple services glued together with schema stitching. Either way, migrating them towards a Federated architecture is rather simple.

WunderGraph allows you to combine multiple Services into a single GraphQL API. It's possible to use Federation and schema stitching at the same time, you can even add REST APIs and databases like PostgreSQL or MySQL to your API.

WunderGraph does so by creating a facade on top of all your services. Once the facade is established, you're able to "move" the implementation of your API out of the monolithic architecture into microservices. As long as the schema stays the same, you're able to move the implementation wherever you want. WunderGraph will glue all services together without introducing any breaking changes for API consumers.

This means, you're able to migrate type by type, field by field in tiny steps out of your monolith. You're able to test the new architecture very early on and can always switch back to the monolith if anything goes wrong.

Once all logic is migrated off of the monolith, your schema will solely depend on the federated services. You're then able to shut down your old systems. This is rather easy compared to the multi-step process above because you're able to keep your API contract intact all the time.

At the very beginning, you're introducing the WunderGraph facade between your clients and your existing infrastructure. WunderGraph makes sure this facade stays intact throughout the whole process of migrating business logic from one place to another.

The Elephant in the room: Apollo GraphQL Federation with Subscriptions

Implementing a GraphQL Gateway with support for Federation is hard. Implementing the same functionality with support for Subscriptions is an even bigger challenge. When this post was written in 2021, few gateways supported both.

That has since changed across the ecosystem, and federated subscriptions are now common. What sets the WunderGraph approach apart today is how the Router handles them. The engine is open source under Apache 2.0, and the Cosmo Router supports subscriptions over WebSockets, Server-Sent Events, and Multipart HTTP out of the box. The bigger shift is event-driven federated subscriptions, covered next.

How Cosmo does federated subscriptions today: Cosmo Streams (EDFS)

The modern way to run subscriptions across a federated graph is Cosmo Streams (event-driven federated subscriptions, or EDFS). Instead of each subgraph holding open WebSocket connections and pushing data through the graph, the Cosmo Router connects directly to your event source and streams updates to subscribers itself.

The Router supports Kafka, NATS, and Redis as event sources. You declare subscriptions in your schema with directives like @edfs__kafkaSubscribe, @edfs__natsSubscribe, or @edfs__redisSubscribe, and the Router does the rest. It holds the subscriber connections, applies per-subscriber filtering and authorization centrally, and keeps your subgraphs HTTP-only and stateless.

On the client side, the Router speaks WebSockets (graphql-ws), Server-Sent Events, and Multipart HTTP, so clients pick whatever transport fits.

For the full picture, see Event-Driven Federated Subscriptions in the docs, the EDFS announcement, and native subscriptions with the Cosmo Router.

What does it all mean for you?

Subscriptions are an essential part of GraphQL, allowing you to build applications that update in Realtime.

With our advanced resolver techniques it's possible to resolve Queries, Mutations as well as Subscriptions with minimal overhead.

Out of the box support for Subscriptions, even in federated environments means, you're able to implement GraphQL services without any extra steps. Just implement the Subscription resolvers in your language and framework of choice, WunderGraph glues it all together.

You don't have to make any changes to your architecture just because you want to adopt federation.

WunderGraph comes with a full bag of goodies

WunderGraph is not just fast. It's the result of my frustration over the complexity of setting up new projects and maintaining them. From Getting Started to running in production, I was super unsatisfied with the complexity involved.