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. Itβs backwards compatible, requiring no major changes to your subgraphs. Try the alpha today!
- Welcome
- Prerequisites
- Build your first graph
- Local development
- Open Telemetry
- Composition examples
- Apollo Workbench
- Apollo Router
Apollo Federation is an architecture for declaratively composing APIs into a unified graph. Each team can own their slice of the graph independently, empowering them to deliver autonomously and incrementally.
Designed in collaboration with the GraphQL community, Federation 2 is a clean-sheet implementation of the core composition and query-planning engine at the heart of Federation, to:
- streamline common tasks - like extending a type
- simplify advanced workflows - like migrating a field across subgraphs with no downtime
- improve the developer experience - by adding deeper static analysis, cleaner error messages, and new composition hints that help you catch errors sooner and understand how your schema impacts performance.
Federation 2 adds:
- first-class support for shared interfaces, enums, and other value types
- cleaner syntax for common tasks -- without the use of special keywords or directives
- flexible value type merging
- improved shared ownership for federated types
- deeper static analysis, better error messages and a new generalized composition model
- new composition hints let you understand how your schema impacts performance
- lots more!
Learn more:
Let's get started!
You'll need:
To install rover
:
curl -sSL https://rover.apollo.dev/nix/v0.4.0 | sh
For help with rover
see installing the Rover CLI.
- Create a free Apollo Studio account
- Select
Register a deployed graph
(free forever) - Create your user & org
- Follow the prompt to add your first graph with the
Deployed
option selected - Navigate to the Federation tab and note the
APOLLO_KEY
andAPOLLO_GRAPH_REF
It should look like this:
Then publish the 3 subgraph schemas to the registry in Apollo Studio.
# build a supergraph from 3 subgraphs: products, users, inventory
make publish
It will prompt you for your APOLLO_KEY
and your APOLLO_GRAPH_REF
that you saved from the step above.
This will initially result in an following error:
---------------------------------------
subgraph: users
---------------------------------------
+ rover subgraph publish My-Graph-2-35jcu9@current --routing-url http://users:4000/graphql --schema subgraphs/users/users.graphql --name users --convert
Publishing SDL to My-Graph-2-35jcu9@current (subgraph: users) using credentials from the default profile.
error: Errors validating subgraph schemas: [{"message":"Subgraph products: Interface ProductItf cannot implement interfaces with subgraph schemas. Contact Apollo support if you're interested in using this GraphQL feature with federation."}]
but we can fix that by enabling Federation 2
in Apollo Studio:
First navigate to your graph settings:
Then enable Federation 2
:
With Federation 2 enabled, the Federated graph composes successfully in Apollo Studio:
Now that Federation 2 is enabled we can start a v2 Gateway that uses the graph composed by Apollo Studio.
This can be done with a single command, or step by step with the instructions that follow:
make demo
make demo
does the following things:
make docker-up
this uses docker-compose.managed.yml
:
version: '3'
services:
apollo-gateway:
container_name: apollo-gateway
build: ./gateway
env_file: # created automatically during `make publish`
- graph-api.env
ports:
- "4000:4000"
products:
container_name: products
build: ./subgraphs/products
inventory:
container_name: inventory
build: ./subgraphs/inventory
users:
container_name: users
build: ./subgraphs/users
which shows:
docker-compose -f docker-compose.managed.yml up -d
Creating network "supergraph-demo_default" with the default driver
Creating apollo-gateway ... done
Starting Apollo Gateway in managed mode ...
Apollo usage reporting starting! See your graph at https://studio.apollographql.com/graph/supergraph-router@dev/
π Server ready at http://localhost:4000/
make query
which issues the following query that fetches across 3 subgraphs:
query Query {
allProducts {
id
sku
createdBy {
email
totalProductsCreated
}
}
}
with results like:
{
data: {
allProducts: [
{
id: "apollo-federation",
sku: "federation",
createdBy: {
email: "[email protected]",
totalProductsCreated: 1337
}
},{
id: "apollo-studio",
sku: "studio",
createdBy:{
email: "[email protected]",
totalProductsCreated: 1337
}
}
]
}
}
Apollo Explorer helps you explore the schemas you've published and create queries using the query builder.
Getting started with Apollo Explorer:
- Ensure the graph we previously started with
make docker-up
is still running - Configure Explorer to use the local v2 Gateway running on http://localhost:4000/
- Use the same query as before, but this time in Apollo Explorer:
query Query {
allProducts {
id
sku
createdBy {
email
totalProductsCreated
}
}
}
Once we're done we can shut down the v2 Gateway and the 3 subgraphs:
docker-compose down
That's it!
This section assumes you have docker
, docker-compose
and the rover
core binary installed from the Prerequisites sections above.
curl https://rover.apollo.dev/plugins/rover-fed2/nix/v0.4.0 | sh
For help with rover
see installing the Rover CLI.
See also: Apollo Federation docs
You can federate multiple subgraphs into a supergraph using:
make demo-local
which does the following:
# build a supergraph from 3 subgraphs: products, users, inventory
make supergraph
which runs:
rover fed2 supergraph compose --config ./supergraph.yaml > supergraph.graphql
and then runs:
make docker-up-local
Creating apollo-gateway ... done
Creating inventory ... done
Creating users ... done
Creating products ... done
Starting Apollo Gateway in local mode ...
Using local: supergraph.graphql
π Graph Router ready at http://localhost:4000/
make demo-local
then issues a curl request to the graph router via:
make query
which issues the following query that fetches across 3 subgraphs:
query Query {
allProducts {
id
sku
createdBy {
email
totalProductsCreated
}
}
}
with results like:
{
data: {
allProducts: [
{
id: "apollo-federation",
sku: "federation",
createdBy: {
email: "[email protected]",
totalProductsCreated: 1337
}
},{
id: "apollo-studio",
sku: "studio",
createdBy:{
email: "[email protected]",
totalProductsCreated: 1337
}
}
]
}
}
make demo-local
then shuts down the graph router:
docker-compose down
make docker-up-local
- Open http://localhost:4000/
- Click
Query your server
- Run a query:
query Query {
allProducts {
id
sku
createdBy {
email
totalProductsCreated
}
}
}
View results:
docker-compose down
To see where time is being spent on a request we can use Open Telemetry Distributed Tracing for Apollo Federation.
make docker-up-otel-collector
make smoke
browse to http://localhost:9411/
make docker-down-otel-collector
You can send Open Telemetry from the Gateway to Honeycomb with the following collector-config.yml:
receivers:
otlp:
protocols:
grpc:
http:
cors_allowed_origins:
- http://*
- https://*
exporters:
otlp:
endpoint: "api.honeycomb.io:443"
headers:
"x-honeycomb-team": "your-api-key"
"x-honeycomb-dataset": "your-dataset-name"
service:
pipelines:
traces:
receivers: [otlp]
exporters: [otlp]
- Docs: Open Telemetry for Apollo Federation
- Docker compose file: docker-compose.otel-collector.yml
- Helper library: supergraph-demo-opentelemetry
- See usage in:
The Apollo Router is our next-generation GraphQL Federation runtime written in Rust, and it is fast.
Early benchmarks show that the Router adds less than 10ms of latency to each operation, and it can process 8x the load of the JavaScript Apollo Gateway.
To get started with the Router:
make demo-local-router
this uses a simple docker-compose.router.yml file:
version: '3'
services:
apollo-router:
container_name: apollo-router
build: ./router
volumes:
- ./supergraph.graphql:/etc/config/supergraph.graphql
- ./router/configuration.yaml:/etc/config/configuration.yaml
ports:
- "4000:4000"
products:
container_name: products
build: ./subgraphs/products
inventory:
container_name: inventory
build: ./subgraphs/inventory
users:
container_name: users
build: ./subgraphs/users
which uses the following Dockerfile
from ubuntu
WORKDIR /usr/src/app
RUN apt-get update && apt-get install -y \
libssl-dev \
curl \
jq
COPY install.sh .
COPY run.sh .
RUN ./install.sh
CMD [ "/usr/src/app/run.sh" ]
see ./router for more details.
- Blog Post
- Docs
- Community Forum -- we'd love to hear what you think!