Federation quickstart

In the previous parts of this quickstart, we used Apollo-hosted services for our subgraphs. Now, let's see what we can do with our own subgraphs.

A service that you want to act as a subgraph can use any GraphQL server that supports Apollo Federation. This includes Apollo Server, along with the other servers listed in Subgraph-compatible libraries.

1. Configure Apollo Server

If you have an existing GraphQL API that uses Apollo Server, you can use that server as a subgraph with the @apollo/subgraph library. You can get started with this example server (which is not yet federated).

First, install the latest version of the @apollo/subgraph library in your project:

1
npm install @apollo/subgraph

Next, import the buildSubgraphSchema function in the file where you initialize ApolloServer:

1
const { buildSubgraphSchema } = require('@apollo/subgraph');

Finally, modify your ApolloServer constructor by passing it a schema option instead of typeDefs and resolvers, like so:

1
const server = new ApolloServer({
2
  schema: buildSubgraphSchema({ typeDefs, resolvers })
3
});

(As shown, you now pass your typeDefs and resolvers to buildSubgraphSchema.)

And that's it! You can now perform all of the same subgraph setup on your own service (schema registration, introspection, etc.) that you did with the Apollo-hosted services we used in the previous parts. Refer to those parts for guidance.

2. Learn about federated types

In a federated graph, each subgraph's schema can define or reference types and fields that are present in another subgraph's schema.

Consider the Product type in our composed supergraph schema from Part 3. This type includes the following fields:

1
type Product
2
  @join__type(graph: PRODUCTS, key: "id")
3
  @join__type(graph: REVIEWS, key: "id", extension: true)
4
{
5
  id: ID!
6
  title: String @join__field(graph: PRODUCTS)
7
  url: String @join__field(graph: PRODUCTS)
8
  # ...additional fields...
9
  reviews: [Review] @join__field(graph: REVIEWS)
10
  reviewSummary: ReviewSummary @join__field(graph: REVIEWS)
11
}

As the federation-specific @join__field directive suggests, these four fields of the same object type are defined across two different subgraphs!

This is possible because our products subgraph schema defines the Product object type as an entity. Entities are object types that multiple subgraphs can contribute fields to.

It makes logical sense that the reviews field of a Product should be resolved by the reviews subgraph instead of the products subgraph. This reflects the design principle of separation of concerns.

Learn how to work with entities.

3. Try out schema checks

After you've registered your first subgraph schema, you can try out one of Apollo Studio's most powerful features: schema checks.

With schema checks, you can check whether some changes you want to make to your schema will affect any of the clients that use your graph. This feature is at its most powerful in your CI/CD environment, where you can automatically detect breaking schema changes before they're deployed to production.

1. Learn about the basics of schema checks
2. Learn about using schema checks with Apollo Federation
3. Learn how to use Rover in a CI/CD environment

Congratulations, you've completed the federation quickstart! If you have any feedback or suggestions for this tutorial, please click Rate article on the right.