July 7, 2022

Building a unified GraphQL API with Apollo Router

Overview

In this article, you will see a practical example of building a unified GraphQL API (supergraph) composed of multiple GraphQL APIs (subgraphs). This is achieved with Apollo Router whose first version was recently released.

The Apollo Router is written in Rust, which provides better performance over Node.js-based @apollo/gateway library (usage of the latter was covered in my previous article). Apollo Router supports any existing Apollo Federation architecture (v1 or v2). Apollo Router as well as several other Apollo tools are licensed under the Elastic License v2 (ELv2).

After replacing Apollo Gateway with Apollo Router, the project architecture looks like this:

architecture

There are only two changes in the diagram compared to the previous version of the architecture: Apollo Router replaced Apollo Server and the project is no longer deployed to GCP.

In such an architecture, all subgraphs should support Apollo Federation, particularly by providing SDL endpoint (query { _service { sdl } }).

The source code of the project is available on GitHub and GitLab.

Configuration

Unlike @apollo/gateway, the Apollo Router is usually packaged as a static, standalone binary, so the task of launching this tool is reduced to the configuration of Apollo Router to customize its behavior, without the need to write custom code. (Yet writing custom code is possible and will be described in the customization section.)

To make Apollo Router work the same way as the previous @apollo/gateway-based implementation (but with improved performance), it was needed to create two files: one — containing supergraph schema and the second — with the router configuration.

Supergraph schema

As a best practice, a gateway does not compose its supergraph schema (the opposite was the case when using @apollo/gateway). Instead, a separate process composes the schema and provides it to the gateway. This helps improve reliability and reduce downtime when you make changes to a subgraph.

There are multiple ways to compose a supergraph schema from subgraph schemas:

The documentation says that the former approach is strongly recommended for production environments but for this demo project the latter is enough.

Before using Rover CLI, all three Rust microservices in the project should be started. The simplest way to do it is by executing docker compose up --build (the launch of the project was covered in detail in the previous post). To generate a file containing supergraph schema, the following command is performed inside the apollo-router directory:

rover supergraph compose --config supergraph.yaml > supergraph.graphql

The command uses the following config:

Listing 1. The supergraph.yaml file
federation_version: 2

subgraphs:
  planets-service:
    routing_url: http://planets-service:8001
    schema:
      subgraph_url: http://localhost:8001
  satellites-service:
    routing_url: http://satellites-service:8002
    schema:
      subgraph_url: http://localhost:8002
  auth-service:
    routing_url: http://auth-service:8003
    schema:
      subgraph_url: http://localhost:8003

  • routing_url is the URL a gateway will use to send GraphQL operations to a subgraph at runtime

  • schema.subgraph_url is the URL that Rover will use to fetch the subgraph schema during composition

The URLs may or may not be the same; in this case, the URLs differ. For example, planets-service.schema.subgraph_url is http://localhost:8001 because I have Rover CLI installed locally, and it fetches SDL endpoint ({ _service { sdl } }) of planets-service which is deployed in the Docker environment and accessible from localhost (by port publishing), but routing_url is http://planets-service:8001 because at runtime, in the Docker environment, Apollo Router calls services by their names.

More information on configuring Rover CLI is available in the documentation.

The output file generated by the command above will be used by Apollo Router.

Note: Apollo Router doesn’t support subscriptions. Even though the output file contains a definition of one provided by planets-service and that subscription is discoverable in a GraphQL client, it cannot be executed.

Router configuration

The second file we need to start Apollo Router is the router.yaml:

Listing 2. The router.yaml file
supergraph:
  listen: 0.0.0.0:4000
  introspection: true

sandbox:
  enabled: true

homepage:
  enabled: false

headers:
  all:
    request:
      - propagate:
          named: role

plugins:
  demo.jwt_validation:
    secret_key: ${env.JWT_SECRET_KEY}

Here are set up:

  • configuration of the HTTP server: socket address and port to listen on

  • enabling introspection required for sandbox to work

  • enabling sandbox (we will use this in the Testing section) and disabling homepage (you can only enable one of these)

  • header propagation: Apollo Router will include the role header to requests to all subgraphs (the role header is created by a custom Apollo Router plugin; its creation will be covered later)

  • configuration of a custom Apollo Router plugin

See the documentation for more configuration options.

The usage of supergraph schema and router configuration files will be shown in the launch section.

Paths to both these files can be specified in environment variables and will be read from .env file or Docker Compose file depending on how you launch Apollo Router in this project.

Customization. Implementation of a plugin

To implement functionality that is not included in the default Apollo Router distribution, you can write customizations. Apollo Router supports two types of customizations:

Rhai scripts should be used when it is possible. But in this project, I used the latter option because the plugin described below requires access to some Rust crates. The plugin performs authorization: it checks whether JWT is specified in an incoming GraphQL request, validates it, extracts a user’s role, and passes the role in a header to downstream microservices. The implementation of the plugin made it possible to remove authorization code from the microservices which no longer need to work with JWTs and can obtain a user’s role from the header if it is passed by the plugin.

Please note that this example is a demonstration of how to create an Apollo Router plugin; for production use of JWT-authorization and authentication, do more research.

Native Rust plugins require building a custom Apollo Router binary that includes your plugin code. Before the development of the plugin, I needed to install npm and rustfmt. These tools are also included in a Dockerfile created to launch the binary in the Docker environment:

Listing 3. Specifying dependencies required to build custom Apollo Router binary
RUN rustup component add rustfmt
RUN apt-get update && apt-get install -y npm

Next, we need to specify a dependency:

Listing 4. Specifying apollo-router dependency
[dependencies]
...
apollo-router = "1.0.0"
...

An entry point of the application looks like this:

Listing 5. The entry point of the application
use anyhow::Result;
use dotenv::dotenv;

mod jwt_validation;

fn main() -> Result<()> {
    dotenv().ok();
    apollo_router::main()
}

The main code of the plugin is in the jwt_validation module.

All plugins require an associated configuration; in this project, the configuration takes just one parameter:

Listing 6. Configuration of the plugin
#[derive(Deserialize, JsonSchema)]
struct JwtValidationConfig {
    secret_key: String,
}

The secret_key field will be populated with the value of the corresponding parameter defined in the router.yaml configuration file which was shown earlier. This parameter specifies a JWT secret that will be used to decode and verify JWT; it has the same value as in auth-service where JWTs are generated.

Next, we define the plugin itself and specify the configuration as an associated type:

Listing 7. Definition of the plugin
#[derive(Debug)]
struct JwtValidation {
    secret_key: String,
}

#[async_trait::async_trait]
impl Plugin for JwtValidation {
    type Config = JwtValidationConfig;

    async fn new(init: PluginInit<Self::Config>) -> Result<Self, BoxError> {
        Ok(JwtValidation {
            secret_key: init.config.secret_key,
        })
    }

    ...

}

All router plugins must implement the Plugin trait. This trait defines lifecycle hooks that enable hooking into Apollo Router services and provides a default implementation for each hook, so we can only define the hooks that are associated with Apollo Router services we need to customize. In this project, according to the documentation, it is SupergraphService, so it is needed to define the supergraph_service function:

Listing 8. Definition of supergraph_service function
#[async_trait::async_trait]
impl Plugin for JwtValidation {

    ...

    fn supergraph_service(&self, service: supergraph::BoxService) -> supergraph::BoxService {
        let jwt_secret_key = self.secret_key.clone();

        let handler = move |request: supergraph::Request| {
            let headers = request.supergraph_request.headers();
            let maybe_auth_header_value = headers.get(AUTHORIZATION_HEADER_NAME);

            let jwt = match maybe_auth_header_value {
                Some(auth_header_value) => {
                    let auth_header_value_str = auth_header_value.to_str()?;
                    get_jwt_from_header_value(auth_header_value_str).to_string()
                }
                None => return Ok(ControlFlow::Continue(request)),
            };

            match decode_jwt(&jwt, &jwt_secret_key) {
                Ok(token_data) => {
                    let role = token_data.claims.role;
                    debug!("User role is: {}", &role);
                    request.context.insert(ROLE_CONTEXT_PARAM_NAME, role)?;

                    Ok(ControlFlow::Continue(request))
                }
                Err(e) => {
                    let error_message = format!("JWT is invalid: {}", e);
                    let response = supergraph::Response::error_builder()
                        .error(graphql::Error::builder().message(error_message).build())
                        .status_code(StatusCode::BAD_REQUEST)
                        .context(request.context)
                        .build()?;

                    Ok(ControlFlow::Break(response))
                }
            }
        };

        let request_mapper = |mut request: supergraph::Request| {
            let maybe_user_role: Option<String> = request
                .context
                .get(ROLE_CONTEXT_PARAM_NAME)
                .expect("This should not return an error");

            if let Some(user_role) = maybe_user_role {
                request.supergraph_request.headers_mut().insert(
                    ROLE_HEADER_NAME,
                    user_role
                        .try_into()
                        .expect("Role should always be converted to HeaderValue"),
                );
            }

            request
        };

        ServiceBuilder::new()
            .checkpoint(handler)
            .map_request(request_mapper)
            .service(service)
            .boxed()
    }
}

To define custom logic for a service hook, you can use ServiceBuilder. ServiceBuilder provides common building blocks that remove much of the complexity of writing a plugin. These building blocks are called layers. In the given implementation of a plugin, two layers are used: checkpoint and map_request. The first performs a sync call to decide whether a request should proceed, specifically, checks whether JWT is specified in the Authorization header and if yes, is it valid or not (based on a result of the decode_jwt function); if the JWT is valid, the function inserts a decoded role to a request’s context to use in a next layer. If a role is presented in the context, the map_request layer adds the role header to the request, and further this header can be used in downstream services to check whether a user has rights to access a particular GraphQL operation.

It would also be possible to add the role header in the checkpoint layer; it is done in the map_request layer for illustration of using a request’s context. The context could also be used to pass custom data between services in the router; in the considered example, a user’s role could be passed between SupergraphService and SubgraphService so that each SubgraphService responsible for a certain downstream service could decide whether to include the role to headers or to process the role in some other way.

To enable the Apollo Router to discover your plugin, you need to register the plugin:

Listing 9. Plugin registration
register_plugin!("demo", "jwt_validation", JwtValidation);

The macro takes 3 arguments: a group name, a plugin name, and a struct implementing the Plugin trait.

You can find more examples of the implementation of plugins in the Apollo Router repository; specifically, there is a more sophisticated example of JWT-based authentication.

Launch

The launch of the whole project with Docker Compose was described in the previous article. In this section, I’ll focus on how to launch a customized Apollo Router. It can be done in two ways:

  • binary

    Use cargo run inside the apollo-router directory. The application will take configuration parameters from .env file using dotenv crate, so you don’t need to explicitly specify them (otherwise, it would be something like cargo run — -s ./supergraph.graphql -c ./router.yaml.

  • Docker image

    In its turn, the container can be started in two ways:

    • base configuration (it uses a pre-created image that is built using GitHub Actions)

      docker-compose -f docker-compose.yml up

      Listing 10. Apollo Router service in Docker Compose file
      version: '3.9'
services:
  ...

  apollo-router:
    image: kudryashovroman/graphql-rust:apollo-router
    container_name: apollo-router
    restart: always
    depends_on:
      - planets-service
      - satellites-service
      - auth-service
    environment:
      APOLLO_ROUTER_SUPERGRAPH_PATH: /apollo-router/schema/supergraph.graphql
      APOLLO_ROUTER_CONFIG_PATH: /apollo-router/config/router.yaml
      APOLLO_ROUTER_LOG: debug
      APOLLO_TELEMETRY_DISABLED: 1
      JWT_SECRET_KEY: $JWT_SECRET_KEY
    volumes:
      - ./apollo-router/supergraph.graphql:/apollo-router/schema/supergraph.graphql
      - ./apollo-router/router.yaml:/apollo-router/config/router.yaml
    ports:
      - 4000:4000

  ...

    • development configuration (the image will be built locally)

      docker-compose up --build

      Listing 11. Apollo Router service in Docker Compose file
      version: '3.9'
services:
  ...

  apollo-router:
    build:
      context: .
      dockerfile: ./apollo-router/Dockerfile

Apollo Router will start with two configuration files which generation was described in the Configuration section.

Just in case, I’ll give an example of a launch standard (not customized) image:

Listing 12. Launch of standard Apollo Router image
version: '3.9'
services:
  ...

  apollo-router:
    image: ghcr.io/apollographql/router:v1.0.0
    container_name: apollo-router
    restart: always
    depends_on:
      - planets-service
      - satellites-service
      - auth-service
    environment:
      APOLLO_ROUTER_SUPERGRAPH_PATH: /apollo-router/schema/supergraph.graphql
      APOLLO_ROUTER_CONFIG_PATH: /apollo-router/config/router.yaml
      APOLLO_ROUTER_LOG: debug
      APOLLO_TELEMETRY_DISABLED: 1
    volumes:
      - ./apollo-router/supergraph.graphql:/apollo-router/schema/supergraph.graphql
      - ./apollo-router/router.yaml:/apollo-router/config/router.yaml
    ports:
      - 4000:4000

  ...

In this case, it is also required that router.yaml does not contain the configuration of the custom plugin.

After the application start, you can execute GraphQL operations against localhost:4000.

Testing

For testing, you can use an embedded GraphQL IDE — Apollo Sandbox — or any other third-party IDE. To open the sandbox, navigate to localhost:4000 in your browser.

Consolidated API looks like this:

sandbox

When executing the above query, Apollo Router retrieves the data from planets-service and satellites-service subgraphs.

Next, I’ll try to check how the custom plugin works by calling the createPlanet GraphQL mutation that requires authorization. The mutation is protected by RoleGuard which specifies that it can be called only by users with the Admin role. The request I’ll use for testing is:

Listing 13. Call of GraphQL mutation that requires authorization
mutation {
  createPlanet(
    planet: {
      name: "Pluto"
      type: DWARF_PLANET
      details: { meanRadius: "1188", mass: "1.303e22" }
    }
  ) {
    id
  }
}

If the Authorization header is not specified at all, then the request passes through the router to planets-service, and the response is:

sandbox subgraph error

Subgraph errors redacted is the error message Apollo Router replaces errors in subgraphs with. This is the default behavior that prevents potential leaks of information to a client. There is a plugin that makes it possible to configure the router to propagate subgraph errors to a client.

If you’ll try to execute the request without the Authorization header against localhost:8001 where GraphQL API of planets-service is located, you’ll see the actual response from that service:

playground planets service forbidden

The next case we consider is when the Authorization header contains an expired JWT:

sandbox expired signature

You can see that the plugin didn’t allow the request to pass to planets-service because the JWT was generated quite a long time ago.

Now I’ll try to pass an invalid JWT by adding some symbol (for example, a letter) to the end of the token:

sandbox invalid jwt

Both previous errors were raised in the decode_jwt function that uses the jsonwebtoken crate.

Finally, if a JWT was generated (using the signIn mutation with john_doe and password credentials) no earlier than an hour ago and everything else is fine, then the response looks like this:

sandbox success response

Possible alternatives

There are alternatives to Apollo Router, i.e. tools that can consolidate multiple GraphQL APIs into one. Here is a list of the ones I know:

Please let me know if there is a gateway not included in the list.

Conclusion

In this article, I showed how to configure, customize, and launch Apollo Router which allows combining multiple GraphQL APIs into a unified supergraph. Apollo Router provides better performance and developer experience and is easier to manage than @apollo/gateway. Also, worth noting is the lack of support for subscriptions. Feel free to contact me if you have found any mistakes in the article or the source code. Thanks for reading!

Useful links

© Roman Kudryashov 2019-2023

Powered by Hugo & Kiss.