Implementing a subgraph with Apollo Server

This article demonstrates how to create a subgraph for a federated supergraph using Node.js and Apollo Server.

Defining a subgraph

Converting an existing monolithic graph into a single subgraph is a convenient first step in building a federated supergraph. To start, here's a non-federated Apollo Server setup:

1
const { ApolloServer, gql } = require('apollo-server');
2

3
const typeDefs = gql`
4
  type Query {
5
    me: User
6
  }
7

8
  type User {
9
    id: ID!
10
    username: String
11
  }
12
`;
13

14
const resolvers = {
15
  Query: {
16
    me() {
17
      return { id: "1", username: "@ava" }
18
    }
19
  }
20
};
21

22
const server = new ApolloServer({
23
  typeDefs,
24
  resolvers,
25
});
26

27
server.listen(4001).then(({ url }) => {
28
    console.log(`🚀 Server ready at ${url}`);
29
});

This should look familiar if you've set up Apollo Server before. If you haven't, we recommend you familiarize yourself with the basics before jumping into federation.

Now, let's convert this to a subgraph!

1. Install and import @apollo/subgraph

The first step is to install the @apollo/subgraph package in our server project:

1
npm install @apollo/subgraph

We also need to require the buildSubgraphSchema function from this package in our index.js file (we'll use it later):

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

2. Opt in to Federation 2

For a subgraph to use new features in Federation 2, its schema needs to include the following extend schema definition:

1
const typeDefs = gql`
2
extend schema
3
  @link(url: "https://specs.apollo.dev/federation/v2.0",
4
        import: ["@key", "@shareable"])
5

6
  type Query {
7
    me: User
8
  }
9

10
  type User {
11
    id: ID!
12
    username: String
13
  }
14
`;

This definition enables the schema to use Federation 2 features. Without it, Federation 2 composition assumes that a subgraph is using Federation 1, which sets certain defaults for backward compatibility.

3. Define an entity

As part of our federated architecture, we want other subgraphs to be able to contribute fields to the User type. To enable this, we add the @key directive to the User type's definition to designate it as an entity:

1
const typeDefs = gql`
2
  extend schema
3
    @link(url: "https://specs.apollo.dev/federation/v2.0",
4
          import: ["@key", "@shareable"])
5

6
  type Query {
7
    me: User
8
  }
9

10
  type User @key(fields: "id") {
11
    id: ID!
12
    username: String
13
  }
14
`;

The @key directive tells the gateway which field(s) of the User entity can uniquely identify a particular instance of it. In this case, the gateway can use the single field id.

Next, we add a reference resolver for the User entity. A reference resolver tells the gateway how to fetch an entity by its @key fields:

1
const resolvers = {
2
  Query: {
3
    me() {
4
      return { id: "1", username: "@ava" }
5
    }
6
  },
7
  User: {
8
    __resolveReference(user, { fetchUserById }){
9
      return fetchUserById(user.id)
10
    }
11
  }
12
};

(This example requires defining the fetchUserById function to obtain the appropriate User from our backing data store.)

4. Generate the subgraph schema

Finally, we use the buildSubgraphSchema function from the @apollo/subgraph package to augment our schema definition with federation support. We provide the result of this function to the ApolloServer constructor:

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

5
server.listen(4001).then(({ url }) => {
6
    console.log(`🚀 Server ready at ${url}`);
7
});

The server is now ready to act as a subgraph in a federated graph!

Combined example

Here are the snippets above combined (again, note that for this sample to be complete, you must define the fetchUserById function for your data source):

1
const { ApolloServer, gql } = require('apollo-server');
2
const { buildSubgraphSchema } = require('@apollo/subgraph');
3

4
const typeDefs = gql`
5
  extend schema
6
    @link(url: "https://specs.apollo.dev/federation/v2.0",
7
          import: ["@key", "@shareable"])
8

9
  type Query {
10
    me: User
11
  }
12

13
  type User @key(fields: "id") {
14
    id: ID!
15
    username: String
16
  }
17
`;
18

19
const resolvers = {
20
  Query: {
21
    me() {
22
      return { id: "1", username: "@ava" }
23
    }
24
  },
25
  User: {
26
    __resolveReference(user, { fetchUserById }){
27
      return fetchUserById(user.id)
28
    }
29
  }
30
}
31

32
const server = new ApolloServer({
33
  schema: buildSubgraphSchema({ typeDefs, resolvers })
34
});
35

36
server.listen(4001).then(({ url }) => {
37
    console.log(`🚀 Server ready at ${url}`);
38
});

Securing your subgraphs

Because of the power and flexibility of the Query._entities and Query._service fields, your subgraphs should not be directly accessible by clients. Instead, only your graph router should have access to your subgraphs. Clients then communicate with the router:

Make sure to implement any necessary firewall rules, access control lists, or other measures to ensure that individual subgraphs can be accessed only via the router.

Disabling CORS

We recommend that subgraphs do not enable CORS (or at least do not use the wildcard access-control-allow-origin: * header). This prevents attackers from exploiting a user's browser to access a subgraph directly.

For Apollo Server subgraphs, you need to disable the default wildcard CORS policy (which is appropriate for many publicly-exposed servers but not for inaccessible servers like subgraphs). For details, see the Apollo Server CORS documentation.

Subgraph-specific fields

When you generate your subgraph schema, some federation-specific definitions are automatically added to it. In addition to directive definitions like @key, the most useful of these definitions for debugging are two fields of the Query type: _service and _entities:

1
type Query {
2
  # ...your field definitions...
3

4
  # Added automatically
5
  _service: _Service!
6
  _entities(representations: [_Any!]!): [_Entity]!
7
}

Query._service

This field returns a _Service object with one field of its own: sdl. You can query it like so:

1
query GetSubgraphSchema {
2
  _service {
3
    sdl
4
  }
5
}

The sdl field returns your subgraph's schema as an SDL string. This field has a couple of important differences from a standard introspection query that a tool like Apollo Sandbox uses:

• Unlike introspection, the sdl field is not disabled by default in production environments (this is safe if you properly secure your subgraph).
• Unlike introspection, the sdl field's returned string includes federation-specific directives like @key.

Query._entities

This field takes a list of entity representations and returns a list of corresponding entities.

1
_entities(representations: [_Any!]!): [_Entity]!

• The _Any type is a special scalar that enables you to provide entity representations of any valid shape.
• The _Entity type is a generated union type that includes every entity defined in your subgraph's schema.

You can query this field like so, providing a value for the $representations variable as shown:

1
query ($representations: [_Any!]!) {
2
  _entities(representations: $representations) {
3
    ... on User {
4
      id
5
      username
6
    }
7
  }
8
}

1
{
2
  "representations": [
3
    {
4
      "__typename": "User",
5
      "id": "5"
6
    }
7
  ]
8
}

Using in tests and debugging

If you're writing integration tests for your subgraph, you can test the return value of the _entities field for various entity representations that your other subgraphs use.

If you're developing your subgraph in your local environment, you can mock the return value of the _entities field for your other subgraphs so you don't have to connect those subgraphs to their respective data stores.

Custom directives in subgraphs

The method for defining custom directives differs slightly for a federated graph, and it also depends on the version of Apollo Server you're using.

Directives in Apollo Server 3.x

Apollo Server 3 does not provide built-in support for custom directives, but you can install certain @graphql-tools libraries to enable support. To get started with these libraries in Apollo Server, first read Creating schema directives.

As the linked article describes, in Apollo Server 3 you define a transformer function for each of your subgraph schema's custom directives.

To apply transformer functions to your executable subgraph schema, you first generate the subgraph schema with buildSubgraphSchema as usual:

1
let subgraphSchema = buildSubgraphSchema({typeDefs, resolvers});

But instead of passing the result directly to the ApolloServer constructor, you first apply all of your transformer functions to it:

1
// Transformer function for an @upper directive
2
subgraphSchema = upperDirectiveTransformer(subgraphSchema, 'upper');

After applying all transformer functions, you provide your final subgraph schema to the ApolloServer constructor as usual:

1
const server = new ApolloServer({
2
  schema: subgraphSchema
3
  // ...other options...
4
});

Directives in Apollo Server 2.x

Without Apollo Federation, you provide your directive definitions to the constructor of ApolloServer in the schemaDirectives argument, like so:

1
const { ApolloServer, gql, SchemaDirectiveVisitor } = require("apollo-server");
2

3
// typeDefs and resolvers defined here
4

5
class DeprecatedDirective extends SchemaDirectiveVisitor {
6
  public visitFieldDefinition(field: GraphQLField<any, any>) {
7
    field.isDeprecated = true;
8
    field.deprecationReason = this.args.reason;
9
  }
10
}
11

12
const server = new ApolloServer({
13
  typeDefs,
14
  resolvers,
15
  schemaDirectives: {
16
    deprecated: DeprecatedDirective
17
  }
18
});

With Apollo Federation, you instead call SchemaDirectiveVisitor.visitSchemaDirectives, passing in your schema and your directives, before you provide your schema to the constructor of ApolloServer:

1
const { ApolloServer, gql, SchemaDirectiveVisitor } = require('apollo-server');
2
const { buildSubgraphSchema } = require ('@apollo/subgraph')
3

4
// typeDefs and resolvers defined here
5

6
class DeprecatedDirective extends SchemaDirectiveVisitor {
7
  public visitFieldDefinition(field: GraphQLField<any, any>) {
8
    field.isDeprecated = true;
9
    field.deprecationReason = this.args.reason;
10
  }
11
}
12

13
const directives = {
14
  deprecated: DeprecatedDirective
15
};
16
let schema = buildSubgraphSchema({ typeDefs, resolvers });
17

18
SchemaDirectiveVisitor.visitSchemaDirectives(schema, directives);
19

20
const server = new ApolloServer({
21
  schema: schema
22
});

Also make sure to read about the gateway's support for custom directives.