GraphQL Federated Schemas Introspection With Mercurius

What is GraphQL federation?

With regards to GraphQL Federated schemas, Apollo federation v1 is one of the most well-known methods of implementing GraphQL in microservices.

The idea is to divide the data graph among multiple federation-compliant services. Then a supergraph schema is composed according to the Apollo federation specification. A client can then query the gateway and access all subgraphs, and the gateway routes the query to the correct services.

The main advantage of a federated architecture is having one single graph that clients can query. However, each subgraph remains independent and flexible enough to be defined, developed, and maintained by separate teams and have its own release cycle. The composed supergraph does not contain information about the subschemas. There is no way to find out from the composed schema where certain types are defined or where fields are extended with new fields. For production deployment that might be ok, but it makes it hard to debug.

Federated schemas in real life

As the supergraph grows, finding which team handles what part of the graph becomes harder. The consumers of the supergraph might need to quickly figure out which team to contact when a bug is found or additional data is required. Mercurius by itself does not expose this information, so from the client perspective the information about federation is completely hidden.

A simple federated scenario

In this scenario we define 2 subgraph schemas. User service is in charge resolving the User entity, Post service resolves the Post entities, but also enhances the User entity with list of posts.

User service schema

This service would be the one that handles the users.

Post service schema

This service would be the one that handles the blog posts.

Gateway supergraph schema

The one graph, where user service schema and post service schema were combined automatically by mercurius following the federation specification.

The composed supergraph schema does not contain information from which service parts of the supergraph are coming from. That is correct for production environment, but makes debugging hard.

Federation info Mercurius plugin

mercurius-federation-info is a simple Mercurius plugin that exposes a custom API that returns every service and details about its subgraph.

The mercurius-federation-info-graphiql-plugin then uses this information to show how the supergraph is constructed.

For the basic usage of the plugin there is no need to install the mercurius-federation-info-graphiql-plugin separately, as it is already included in mercurius-federation-info.

Adding the plugin to Mercurius

Federation info GraphiQL plugin

mercurius-federation-info-graphiql-plugin is the client side of the plugin that adds two views to the GraphiQL interface (already included in mercurius). The views show the details of how the unified schema constructed with schema federation.

Unified Schema Panel

A set of tables displaying information about the unified schema, where we can quickly find which services define or reference various parts of the one graph.

There are currently four main groups: Queries, Mutations, Subscriptions and Types.

When expanded, Queries, Mutations and Subscriptions list every root field (combined from all services). The columns show the information about each field and in which service it is defined.

The Types table list all object types defined across all the federated services.

Services Panel

The Services panel lists all the services that are being federated. When a service is expanded we can see a tree view of all the types that are defined by that service.

The plugin is also available as a standalone GraphiQL plugin.

Restricting access to subgraph details

The plugin can also be used in production as it allows fine-tuned access control.

The enabled option also accepts a function, which can be used to conditionally enable the plugin:

In this way, only requests sent by an hypothetical admin user will have the plugin enabled and contain the detailed subgraph schema.

Conclusions

GraphQL federation on mercurius is a great way to combine multiple subgraphs into one single supergraph and mercurius-federation-info makes it is easier to have a detailed understanding how the unified graph is constructed.

It can aid in communication with other teams, bug reporting and bug discovery. Together with mercurius-explain it helps with the common issues that arise when using graphql in production.

References

• Mercurius implementation of Apollo Federation
• Introduction to Apollo Federation