Apollo Federation composes separately owned GraphQL services into one graph

The repository is a monorepo named after its pipeline stages

Apollo Federation is an architecture for declaratively composing APIs into a unified graph, where each team can own their slice of the graph independently and deliver autonomously and incrementally. The repository layout names the stages of that pipeline. composition-js/ holds the composition logic that merges subgraph schemas into a supergraph. query-graphs-js/ and query-planner-js/ hold the code that turns a query into a plan across subgraphs. gateway-js/ is the runtime that executes the plan. subgraph-js/ is the library a service includes to publish its own schema. Then there are internals-js/ for shared code, federation-integration-testsuite-js/ for the end to end suite, designs/ for the design documents, docs/ for the documentation source, and a codegen.yml driving graphql-codegen. The recent releases are scoped packages such as @apollo/subgraph, @apollo/query-planner and @apollo/query-graphs, all at 2.14.4 from 2026-08-18, which tells you the monorepo publishes several artifacts independently.

Federation 2 changed the ownership model and the syntax

Federation 2 is an evolution of the original Apollo Federation with an improved shared ownership model, enhanced type merging, and cleaner syntax for a smoother developer experience. The key compatibility claim is that it is backwards compatible, requiring no major changes to your subgraphs. The first version is still supported, with the docs and the code on the version-0.x branch, and the branch guidance in the readme is specific about how to get each line. Federation 2 is the current main branch, and installing latest from npm gives the most recent published code from main, while the prior releases live under the version-0.x branch and installing latest-1 gives the most recent published code from that branch. The two version lines are published under different dist tags, so a project that mixes them will find npm resolving them apart, which is the correct behaviour but worth knowing before you add both to one application.

Composition is a build step, not a runtime behaviour

The composition step is what turns a set of subgraphs into a supergraph, and the readme points to a demo repository and to the Federation 2 docs for how to try it. The scripts in the package.json show how much of this is a build pipeline rather than library code. The codegen script runs graphql-codegen against codegen.yml, and there is a check variant that runs the generator and then fails if the working tree changed, which is the pattern of a project where generated artefacts are committed. The error code documentation is generated too, with a script that runs genErrorCodeDoc and writes docs/source/errors.md, again with a check variant, and the same pattern for the hints documentation. Those check scripts are the interesting detail, because they mean a pull request that changes the composition logic and forgets to regenerate the docs fails in CI rather than silently.

The gateway executes a plan it does not own

The description of what Apollo Federation does in practice is worth separating from the composition story. The gateway is used to compose a unified graph from multiple subgraphs, determine a query plan, and route requests across your services. The plan comes from the query planner, the supergraph comes from composition, and the gateway's job is to execute. That separation is the architectural point and also the operational one, because the gateway is now a component whose behaviour depends on a supergraph artefact produced elsewhere, and a change to any subgraph can change the plan. The readme also points at a project roadmap file for what is coming next, and a note in the package list shows the scale of the tooling around the core, with a spell check script that has a dictionary of real words, a release process documented in RELEASING.md, and a changesets directory for versioning.

The licence is per file, and that is unusual

The licensing note in the readme is more careful than most, and a reader deploying this needs to read it. Source code in the repository is covered by either the Elastic License 2.0 or an MIT compatible license, in each case as designated by a licensing file in a subdirectory or a file header, and the default throughout the repository is a license under the Elastic License 2.0 unless a file header or a licensing file in a subdirectory specifies another license. So there is no single answer to what licence applies, and you have to check the directory you are importing. The Elastic License 2.0 is a source-available licence rather than an OSI approved one, which matters for a company shipping a closed product that links these packages, and the MIT compatible alternative exists per file for the parts where it does. The readme also links the Apollo privacy policy, which notes that some Apollo tools and services may gather telemetry, which is a thing to check before enabling Studio or GraphOS integrations alongside a self-hosted gateway.

Where Federation is the wrong choice

Three limits are worth naming. The first is that the machinery only pays off above a certain size. With one service, a supergraph, a composition step and a query planner in the request path are all cost with no benefit, and a plain GraphQL server is simpler. The second is the coupling the architecture introduces, since subgraphs that were independent now share a type system, and the shared ownership model, enhanced type merging and the composition step are all about managing the conflicts that follow, which is a governance cost as much as a technical one. The third is the version landscape, where main carries 2.x while the older 0.x packages stay available under a different dist tag, and a large organisation will have subgraphs on the older line for a while, so the compatibility work is not optional. The readme is candid about the shape of this, with a dedicated demo repository and a community thread asking for feedback, and it points at a roadmap rather than presenting the architecture as finished.

Editorial conclusion

federation suits a large organisation where several teams each own a service and want one GraphQL API in front of them, and it suits a team that has already standardised on GraphQL and needs the composition and planning pieces rather than a schema stitching layer. It is the wrong tool for a single service, where a plain GraphQL server is simpler and has no composition step to reason about. It is also the wrong choice if you need the gateway to be the source of truth, since the gateway routes a supergraph it does not own. Before adopting it, read the Federation 2 migration material, because the syntax and the shared ownership model changed from the first version, and check the branch you install from, since main carries 2.x and version-0.x holds the 0.x packages. The last push was on 2026-10-17 and the recent package releases are 2.14.4.

Frequently asked questions

Official sources

1. apollographql/federation on GitHub
2. Issues
3. Project website
4. README
5. Releases