Using Mercurius with a Schema Registry

As GraphQL becomes increasingly popular, the need for better tooling and orchestration to manage it is becoming more apparent. One of the main challenges is to ensure schemas are valid and up to date across all deployed edge services. This need has led to the development of so-called schema registries, which maintain a single, consistent source of truth across organisations.

One of the most popular registries is Apollo Studio , offered as a free and enterprise cloud service by Apollo GraphQL. In support of open source and standards, Apollo recently released details of its Schema Reporting Protocol, allowing integration with third-party clients outside the Apollo ecosystem. Mercurius is a high-performance GraphQL adapter for the popular Fastify web framework . It already supports the Apollo Federation specification out of the box, and, with the addition of the new Apollo Registry plugin, now integrates with Apollo Studio.

The plugin is available via the NPM registry , with full source code available to review and improve on GitHub . The initial implementation focuses on the upload of a given GraphQL schema to the Apollo Registry, but new features and improvements are already being tracked for future development.

To begin, you will need to register for a free Apollo Studio account . You can use your GitHub credentials for convenience or sign up with an email address and password of your choice. Once you sign in, you can create a new Graph which will have an API key associated with it. Full information on how to do this can be found in the Apollo Studio documentation .

Adding the registry reporting plugin to an existing Mercurius code base is the same as adding any other Fastify plugin. Simply install the plugin with your package manager of choice: npm install mercurius-apollo-registry .

Next, register the plugin with the required options.

Registering the plugin requires two mandatory options. The schema is a string representation of the GraphQL schema you wish to report to the Apollo Registry. The apiKey is the unique API Key for the Graph you wish to send schema updates for. Full information about each of these options can be found in the plugin documentation .

The plugin depends on Mercurius, so it must be added after the Mercurius plugin itself has been registered to satisfy dependencies. Once registered, it will take care of reporting the loaded schema automatically. The plugin uses the same Fastify logging system as Mercurius and by default aims to be conservative in the number of messages raised. By increasing the log verbosity in Fastify (for example from info to debug), the plugin can also be made to report registry responses and payloads to help debug issues.

As changes are made to the schema over time and reported to the registry, a change log is produced in Apollo Studio. This allows you to investigate differences as they evolve over time. As a premium feature, you can also automatically check for breaking changes whenever an updated schema is reported to the registry.

[caption id="attachment_300015215" align="alignnone" width="796"]

Apollo Studio showing the history of various schema changes[/caption]

A detailed description of the protocol has been released as part of the registries documentation to allow third-party clients to integrate successfully with Apollo’s infrastructure. The protocol itself is implemented via GraphQL queries and defines two mutations that should be used for reporting, as well as some retry and timeout logic.

[caption id="attachment_300015216" align="alignnone" width="560"]

Diagram explaining each registry reporting step[/caption]

When an edge server wishes to update the registry with its local schema, it first makes a request with some basic information about itself and includes a SHA2 hash of the schema it wishes to report. If the SHA2 hash differs from the one known by the registry (indicating the schemas no longer match), the registry gives the edge server permission to report their schema in full after an agreed timeout has expired.

The registry expects each edge server to submit a normalised string version of their schema as well as its matching SHA2 hash. The registry can then compare and make changes to the global schema based on the report. This update, if valid and accepted, now replaces the previous schema, and all future reports are judged against this new value.

The key to making this reporting successful is in the normalisation of the schema string itself. The protocol defines rules for how each of the fields should be sorted, how white space should be removed and the consistency required. This allows the registry to interoperate with changes from multiple third-party applications without issue.

The plugin currently supports the basics of schema reporting and aims to be a good foundation for future integration with the Apollo Registry. As an open source plugin, it can be extended and modified over time as the registry adds new functionality and features.

The most eagerly awaited feature is schema reporting with a Federated Graph. While this feature is not currently supported by the Apollo Registry itself, it is certainly on its roadmap. Once it becomes available, it will be an excellent future addition to the plugin as the protocol is expanded. The ability to report metrics to Apollo Studio for various queries may also be of future development interest, as it complements the existing schema-checking functionality.

If you are interested in trying Mercurius, we encourage you to take a look at the GitHub repository and learn how to get started. With the initial feature of schema reporting in place, end users can now benefit from the additional visibility Apollo Studio brings, and they can also use Mercurius as their GraphQL adapter of choice. It is also now possible to combine Mercurius with the various Continuous Integration abilities offered by the Apollo registry, including GitHub checks when a given schema is updated.

This plugin may be small for now, but it is certain to enable a whole new range of possibilities with Mercurius and Apollo.