What is GraphQL

GraphQL is a query language for APIs; it provides a clear and complete description for your data and allows the client to retrieve the data it needs.

The API can be defined using a schema that allows the client to know which operations can be executed by the server — the performance of the operations is determined by the resolvers. Using these concepts makes it easy to define and extend your API.

Once the schema and the resolvers are defined, you can select from any available GraphQL implementations and pick the one that best meets your preferences/requirements.

Initially developed by Facebook, which provided just a reference implementation, GraphQL was mostly implemented in the JS ecosystem in Apollo and Mercurius. Speaking of references, I recommend you view the mercurius-apollo-playground repo created by Andrea Carraro. It provides you with invaluable context because it contains the code and the benchmark commands for the project that inspired this blog post.

Creating a GraphQL server that manages a data structure like the one in the diagram below can be achieved quickly by using a single GraphQL server.

However, real-world applications are more complex than that seen above. Indeed, it’s pretty common for most applications to require hundreds of entities and access to multiple data sources, as the image underneath demonstrates:

We can use a single GraphQL service to build an application as complex as the one above, but the issue with this approach is that a huge codebase is difficult to maintain and split into different teams — some parts can load heavily, others are only called a few times, etc.

A microservices-like approach enables you to split the responsibilities into different services that can be maintained by separate teams and deployed in different ways.

According to the Integrity Principles, having a single entry point with a unified schema is essential. For example, it’s essential in order to be able to access all data from a single query and avoid duplication of graph implementation.

This feature can be created using Apollo federation v1, one of the most well-known methods of implementing GraphQL in microservices.

Define a sample architecture with supergraph and subgraph

Let’s define a schema for the well-known example of a blog page’s basic architecture.

Our system will have two entities:

  • User: This implements the user data and can retrieve the blog post written by a user
  • Post: This implements the post data and can retrieve the information about the author (that’s a specific type of user)

Below, you can see an example of a schema that defines the above entities:

Copy to Clipboard

Based on the above example, we would have two services — the first one manages the users and the second one looks after the posts.

We can split the schema into 2 subgraphs:

Copy to Clipboard

We define the application architecture with three services:

  • Gateway service with a GraphQL endpoint that acts as supergraph service — this exposes a merged schema that’s created using the subgraphs schemas
  • User service with a GraphQL endpoint that serves the supergraph 1 schema
  • Posts service with a GraphQL endpoint that serves the supergraph 2 schema

Implement the application with a gateway

To implement the solution, we can use either Mercurius or Apollo. However, the key thing to note is that we also have the option of picking both libraries and deciding service-by-service which one to use.

First, we define the schema and the resolvers that can be created with an agnostic approach.

Copy to Clipboard
Copy to Clipboard

The User subgraph service with Apollo

The User subgraph service is created using the Apollo framework. It is built by passing a schema created by the buildSubgraphSchema method to the ApolloServer instance. The ApolloServer is then passed to the startStandaloneServer function that exposes the /graphql endpoint.

Copy to Clipboard

The Post subgraph service with Mercurius

The Post subgraph service is created using the Mercurius framework. A Fastify application is created with the @mercuriusjs/federation plugin. The plugin exposes a GraphQL federated service on the /graphql endpoint based on the schema and the resolvers defined in the postSubgraph file.

Copy to Clipboard

The code above shows that the two technologies can be switched quickly if the resolvers are kept agnostic. However, in a real-world example, keeping the agnostic rule valid is more complex and requires serious attention. Authentication, authorization, caching, validation, etc… are created using modules that can be strictly related to either of the platforms.

A good design and a Hexagonal Architecture pattern will help you to achieve the goal of being able to switch the two technologies by keeping the resolvers agnostic.

Create the gateway

We can use the @apollo/gateway or @mercuriusjs/gateway modules to create the gateway. The integration of both technologies is similar:

  • Firstly, they call the subgraph services to get the exposed schema
  • Secondly, they merge them in the supergraph schema, automatically creating the resolvers

The services created above expose the GraphQL endpoint and run on ports 4001 and 4002. The introspection action of the gateway calls the endpoint, merges the subgraph schemas, and provides the client with a unified schema.

Implement the supergraph gateway with Apollo gateway

The Apollo library provides a gateway that can be used as a supergraph server. Setting it up is enough to pass the subgraph endpoints as parameters. You can learn more about this by reading the official documentation for implementing a gateway with Apollo server.

The snippet below creates an Apollo gateway for the services defined above.

Copy to Clipboard

Implement the supergraph gateway with Mercurius gateway

The Mercurius library provides a module (@mercuriusjs/gateway) that creates a supergraph server. As with the Apollo server, setting it up is enough to pass the subgraph endpoints as parameters. You can discover more about this by checking out the official documentation published by Mercurius.

The snippet below creates a Mercurius gateway for the services defined above.

Copy to Clipboard

 Create a supergraph gateway with Apollo Router

In addition to the library I showed you previously in this blog post, Apollo provides a high-performance router that is built in Rust.

A supergraph definition file is required to run the Apollo router. This file can be generated using rover, a command-line interface for managing graphs with GraphOS:

Install rover and follow the instructions to generate the key.

Login to rover.

Copy to Clipboard

Create a YAML config file that declares how to retrieve the subgraph schema.

Copy to Clipboard

You now generate the supergraph file. To do this, the subgraph services should be run and be accessible.

Copy to Clipboard

Install the Apollo router.

Prepare a config file for the router.

Copy to Clipboard

Run the router.

Copy to Clipboard

Run a sample query

Our federation is now up and running. Let’s define a query that uses both subgraphs.

Copy to Clipboard

According to the schema defined above, the following query will be executed:

  • Get the user list and the name of each user in the user service
  • Obtain the post related to each user from the post service
  • Ask the user service again for the information related to the author

Run the test using a CURL command.

Copy to Clipboard

The server will return a similar result.

Copy to Clipboard

Benchmark Overview

The examples above can be merged differently. For instance, they could employ a full Mercurius or Apollo implementation or use a hybrid implementation with the Apollo router and the subgraph managed by Mercurius. There are a number of options.

A simple case like this is easy to convert and to create some benchmarks for the performance that are based on the configuration.

Configurations tested:

  • Mercurius gateway, Mercurius subgraph services
  • Apollo gateway, Mercurius subgraph services
  • Apollo gateway configured with subgraph, Mercurius subgraph services
  • Apollo router (rust), Mercurius subgraph services
  • Apollo gateway, Apollo subgraph services
  • Apollo router (rust), Apollo subgraph services

Test details:

  • The test is run on a MacBookPro 6-Core Intel Core i7, 32GB
  • All the data is mocked in memory and a no database call is carried out
  • The query tested is the sample query defined above
  • The test is done using autocannon with 10 concurrent connections for 10 seconds

It’s important to be aware that this is not a production test and should not be taken as a reference for the performance provided by the library. An accurate production application adds many layers that affect the system’s performance.

Request responses in 10 seconds (the higher the better)

1xx 2xx 3xx 4xx 5xx
apollo-router-with-mercurius-services 0 33119 0 0 0
mercurius-gateway-with-mercurius-services 0 15660 0 0 0
apollo-router-with-apollo-services 0 7468 0 0 0
mercurius-gateway-with-apollo-services 0 7419 0 0 0
apollo-gateway-with-mercurius-services-and-supergraph 0 7341 0 0 0
apollo-gateway-with-mercurius-service 0 5680 0 0 0
apollo-gateway-with-apollo-services 0 3999 0 0 0

Requests per second (the higher the better)

average stddev min max
apollo-router-with-mercurius-services 3011.19 129.66 2733 3223
mercurius-gateway-with-mercurius-services 1566 39.64 1500 1630
apollo-router-with-apollo-services 746.8 39.14 654 807
apollo-gateway-with-mercurius-services-and-supergraph 734.1 25.78 670 768
mercurius-gateway-with-apollo-services 674.46 20.02 621 700
apollo-gateway-with-mercurius-service 568 22.2 535 604
apollo-gateway-with-apollo-services 399.9 18.61 354 421


As I’ve explained in this article, the creation of a hybrid system with Mercurius and Apollo can be achieved quite easily. Furthermore, it is possible to choose other JS libraries or even different languages. Check the supported feature list in the federation-compatible subgraph implementations document to discover what options are available to you.

The configuration you should choose depends on many factors. If the system is well-designed and tested, it is relatively easy to move from one technology to another and run some benchmarks to understand better which solution fits the product requirements.

Now all that’s left is for you to create your own hybrid system with Mercurius and Apollo, when the time is right for you to do so.


Share Me

Related Reading


Don’t miss a beat

Get all the latest NearForm news, from technology to design. Sign up for our newsletter.

Follow us for more information on this and other topics.