Federation
+Apollo Federation offers a means of splitting your monolith GraphQL server into independent microservices. It consists of two components: A gateway and one or more federated microservices. Each microservice holds part of the schema and the gateway merges the schemas into one single schema that can be consumed by the client.
+To quote the Apollo docs, Federation is designed with these core principles
+-
+
- Building a graph should be declarative. With federation, you compose a graph declaratively from within your schema instead of writing imperative schema stitching code. +
- Code should be separated by concern, not by types. Often no single team controls every aspect of an important type like a User or Product, so the definition of these types should be distributed across teams and codebases, rather than centralized. +
- The graph should be simple for clients to consume. Together, federated services can form a complete, product-focused graph that accurately reflects how it’s being consumed on the client. +
- It’s just GraphQL, using only spec-compliant features of the language. Any language, not just JavaScript, can implement federation. +
Note Apollo Federation currently does not support subscriptions, and only the "Schema first" approach is currently supported due to limitations with the decorators not yet supporting GraphQL directives1 ++
In the next example, we'll set up a demo application with a gateway and two federated endpoints; a user- and posts service.
+Federated example: Users
+First make sure you install the optional dependency for federation: npm install --save @apollo/federation.
The User service has a simple schema. Note the @key directive, it tells the Apollo query planner that a particular instance of User can be fetched if you have its id. Also note that we extend the Query type.
+type User @key(fields: "id") {
+ id: ID!
+ name: String!
+}
+
+extend type Query {
+ getUser(id: ID!): User
+}Our resolver has one extra method: resolveReference. It'll called by the Apollo Gateway whenever a related resource requires a User instance. We'll see an example of this in the Posts service later on. Please note the @ResolveReference decorator.
+import { Args, Query, Resolver, ResolveReference } from '@nestjs/graphql';
+import { UsersService } from './users.service';
+
+@Resolver('User')
+export class UsersResolvers {
+ constructor(private readonly usersService: UsersService) {}
+
+ @Query()
+ getUser(@Args('id') id: string) {
+ return this.usersService.findById(id);
+ }
+
+ @ResolveReference()
+ resolveReference(reference: { __typename: string, id: string }) {
+ return this.usersService.findById(reference.id);
+ }
+}Finally, we hook it everything up in a module together with a GraphQLFederationModule. This module accepts the same options as the regular GraphQLModule.
+import { Module } from '@nestjs/common';
+import { GraphQLFederationModule } from '@nestjs/graphql';
+import { UsersResolvers } from './users.resolvers';
+
+@Module({
+ imports: [
+ GraphQLFederationModule.forRoot({
+ typePaths: ['**/*.graphql'],
+ }),
+ ],
+ providers: [UsersResolvers]
+})
+export class AppModule {}
+Federated example: Posts
+The Posts service references the User type in its schema by marking it with the extend keyword. It also adds one property to the User type. Note the @key directive used for matching instances of User, and the @external directive indicating that the id field is managed elsewhere.
+type Post @key(fields: "id") {
+ id: ID!
+ title: String!
+ body: String!
+ user: User
+}
+
+extend type User @key(fields: "id") {
+ id: ID! @external
+ posts: [Post]
+}
+
+extend type Query {
+ getPosts: [Post]
+}Our resolver has one method of interest here: getUser. It returns a reference containing __typename and any additional properties your application needs to resolve the reference, in this case only an id. The __typename is used by the GraphQL Gateway to pinpoint the microservice responsible for the User type and request the instance; The User service discussed above will be called on the resolveReference method.
+import { Query, Resolver, Parent, ResolveProperty } from '@nestjs/graphql';
+import { PostsService } from './posts.service';
+import { Post } from './posts.interfaces';
+
+@Resolver('Post')
+export class PostsResolvers {
+ constructor(private readonly postsService: PostsService) {}
+
+ @Query('getPosts')
+ getPosts() {
+ return this.postsService.findAll();
+ }
+
+ @ResolveProperty('user')
+ getUser(@Parent() post: Post) {
+ return { __typename: 'User', id: post.userId };
+ }
+}
+The Posts service has virtually the same module, but is included below for the sake of completeness
+
+import { Module } from '@nestjs/common';
+import { GraphQLFederationModule } from '@nestjs/graphql';
+import { PostsResolvers } from './posts.resolvers';
+
+@Module({
+ imports: [
+ GraphQLFederationModule.forRoot({
+ typePaths: ['**/*.graphql'],
+ }),
+ ],
+ providers: [PostsResolvers]
+})
+export class AppModule {}Federated example: Gateway
+First make sure you install the optional dependency for the gateway: npm install --save @apollo/gateway.
Our gateway only needs a list of endpoints and will auto-discover the schemas from there. The code for our gateway is therefore very short:
+
+import { Module } from '@nestjs/common';
+import { GraphQLGatewayModule } from '@nestjs/graphql';
+
+@Module({
+ imports: [
+ GraphQLGatewayModule.forRoot({
+ server: {
+ // ... Apollo server options
+ cors: true,
+ },
+ gateway: {
+ serviceList: [
+ { name: 'users', url: 'http://user-service/graphql' },
+ { name: 'posts', url: 'http://post-service/graphql' },
+ ],
+ },
+ }),
+ ],
+})
+export class AppModule {}Warning Apollo recommends that you don't rely on the service discovery in a production environment but use their Graph Manager instead ++
Build Service
+You can customize the requests between the gateway and federated services using a build service. You can easily extend the default RemoteGraphQLDataSource and implement one of the hooks. Please refer to Apollo Docs on RemoteGraphQLDataSource for more information about the possibilities.
+import { Module } from '@nestjs/common';
+import { GRAPHQL_GATEWAY_BUILD_SERVICE, GraphQLGatewayModule } from '@nestjs/graphql';
+import { RemoteGraphQLDataSource } from '@apollo/gateway';
+
+@Module({
+ providers: [
+ {
+ provide: GRAPHQL_GATEWAY_BUILD_SERVICE,
+ useValue: ({ name, url }) => {
+ return new RemoteGraphQLDataSource({ url });
+ },
+ },
+ ],
+ exports: [GRAPHQL_GATEWAY_BUILD_SERVICE],
+})
+class BuildServiceModule {}
+
+@Module({
+ imports: [
+ GraphQLGatewayModule.forRootAsync({
+ useFactory: async () => ({
+ gateway: {
+ serviceList: [/* services */],
+ },
+ }),
+ imports: [BuildServiceModule],
+ inject: [GRAPHQL_GATEWAY_BUILD_SERVICE],
+ }),
+ ],
+})
+export class AppModule {}Async configuration
+Both the Federation and Gateway modules support asynchronous initialisation using the same forRootAsync that's documented in Quick start