GraphQL federation for everyone!

Federation combines the GraphQL APIs from multiple (microservice) teams into a single API. With graphql-transform-federation you can add federation to (managed) GraphQL services, generated GraphQL schemas or other GraphQL APIs. Previously the only way to add federation, was to modify your GraphQL schema. If you didn’t have control over the schema there was no way to use federation.

When do you need federation?

When you have multiple teams creating backend services you want them to be responsible for their own GraphQL schema. Having a single team which creates a GraphQL API for every service, does not scale. Since every team needs to align with the centralized GraphQL team, it would be too much communication overhead. So to scale your development effort you want to have each team be responsible for their own GraphQL API. However, that way you can’t query a single GraphQL API anymore. Because the main idea of GraphQL is having a single API endpoint you want to combine the GraphQL schemas from your different teams. Previously there was an approach called schema stitching. This still required all stitching operations to be implemented in the centralized GraphQL gateway. This is where GraphQL federation comes in. It allows backend teams to define how the different GraphQL APIs are stitched together as metadata in their own GraphQL schema. The GraphQL gateway now only needs to know how the different APIs can be reached and it is able to create a single GraphQL API.

What does graphql-transform-federation do?

Apollo federation requires adding some directives and resolvers to you schema. Graphql-transform-federation will add these to your schema. You can transform the schema defined in the same NodeJS application, but it can also be a remote schema. When using a remote schema it does not matter which technology is used to implement the backend service. You will be running graphql-transform-federation in a middleware service. This even makes it possible to add federation support to managed GraphQL solutions which do not have support yet. Examples are: Hasura, AWS Appsync, Prisma, OneGraph, DatoCMS, GraphCMS, Contentful, etc.

Applying the transform to a local schema makes sense if it don’t have enough control over the schema. This can be the case when it is automatically generated like in swagger-to-graphql, or when your schema builder does not have federation yet, like nexus.
When working with apollo-server (which uses graphql-tools), there is no need to use the transform since federated is supported by default. See the documentation on how how to implement a federated schema with apollo-server.

What does an example look like?

The code below shows a GraphQL schema and what it looks like after transformation. Below that you can see the code on how to perform the transformation. A full working example is available on GitHub, it shows how a schema generated with swagger-to-graphql is extended by another GraphQL service. The gateway combines both schemas into a single graph.

// Original schema
type Pet {
  id: String
  comments: [Comment!]!
}

// Transformed schema
extend type Pet @key(fields = "id"){
  id: String @external
  comments: [Comment!]!
}

// Code to do the transformation
const federatedSchema = transformSchemaFederation(originalSchema, {
  Pet: {
    extend: true,
    keyFields: ['id'],
    fields: {
      id: {
        external: true,
      },
    },
  },
});

Final thoughts

GraphQL is gaining more and more adoption. It makes it feasible to create a single data graph as the API for all services in your company, usable by any client. With federation you can be sure that it will scale to big development organisations. With graphql-transform-federation you can make federation work in any situation. So check out the demo and let me know what you think.