GraphQL Federated Schemas Introspection With Mercurius
26 Jan 2023
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 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.
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.