Gateway: Supergraph schema

Hive Gateway can retrieve a supergraph from a wide range of sources.

This includes:

Hive Schema Schema Registry
Apollo GraphOS / Studio
Custom Sources

In addition you can also proxy any GraphQL API, by either introspection or providing a schema file.

Supergraph

Hive Gateway has built in support for fetching supergraphs from the Hive Schema Registry. You can either choose to provide the configuration via CLI parameters, environment variables or a configuration file.

gateway.config.ts

import { defineConfig } from "@graphql-hive/gateway";

export const gatewayConfig = defineConfig({
  supergraph: {
    type: "hive",
    // The endpoints of Hive's CDN
    endpoint: [
      // Main CDN
      "https://cdn.graphql-hive.com/artifacts/v1/<target_id>",
      // Mirror CDN
      "https://cdn-mirror.graphql-hive.com/artifacts/v1/<target_id>",
    ],
    // The CDN token provided by Hive Registry
    key: "<cdn access token>",
  },
});

hive-gateway supergraph "https://cdn.graphql-hive.com/artifacts/v1/<target_id>" \
  --hive-cdn-key <cdn access token>

Hive Gateway has built in support for fetching supergraphs from the Apollo GraphOS Registry. You can either choose to provide the configuration via CLI parameters, environment variables or a configuration file.

hive-gateway supergraph <graph_id>[@<variant>] --apollo-key <api_key>

gateway.config.ts

import { defineConfig } from '@graphql-hive/gateway'

export const gatewayConfig = defineConfig({
  supergraph: {
    type: 'graphos',
    /**
     * The graph ref of the managed federation graph.
     * It is composed of the graph ID and the variant (`<YOUR_GRAPH_ID>@<VARIANT>`).
     *
     * If not provided, `APOLLO_GRAPH_REF` environment variable is used.
     *
     * You can find a a graph's ref at the top of its Schema Reference page in Apollo Studio.
     */
    graphRef: '<graph_id>[@<variant>]',
    /**
     * The API key to use to authenticate with the managed federation up link.
     * It needs at least the `service:read` permission.
     *
     * If not provided, `APOLLO_KEY` environment variable will be used instead.
     *
     * [Learn how to create an API key](https://www.apollographql.com/docs/federation/v1/managed-federation/setup#4-connect-the-gateway-to-studio)
     */
    apiKey: '<api_key>',
    /**
     * The URL of the managed federation up link. When retrying after a failure, you should cycle through the default up links using this option.
     *
     * Uplinks are available in `DEFAULT_UPLINKS` constant.
     *
     * This options can also be defined using the `APOLLO_SCHEMA_CONFIG_DELIVERY_ENDPOINT` environment variable.
     * It should be a comma separated list of up links, but only the first one will be used.
     *
     * Default: 'https://uplink.api.apollographql.com/' (Apollo's managed federation up link on GCP)
     *
     * Alternative: 'https://aws.uplink.api.apollographql.com/' (Apollo's managed federation up link on AWS)
     */
    upLink?: string;
  }
})

You can provide a custom supergraph source, along with other options to customize the polling/retry behavior.

gateway.config.ts

import { defineConfig } from "@graphql-hive/gateway";

export const gatewayConfig = defineConfig({
  supergraph: () =>
    // Fetch the supergraph from the schema registry
    fetch("https://my-registry.com/supergraph.graphql", {
      headers: {
        Authorization: "Bearer MY_TOKEN",
      },
    }).then((res) => res.text()),

  plugins: (ctx) => [
    // You can also write your custom plugins to interact with the schema registry
    useMyCustomPlugin(ctx),
  ],
});

You can point to supergraph.graphql located in your file system.

hive-gateway supergraph ./supergraph.graphql

gateway.config.ts

import { defineConfig } from "@graphql-hive/gateway";

export const gatewayConfig = defineConfig({
  supergraph: "./supergraph.graphql",
});

Polling

You can configure the polling interval for the supergraph source.

gateway.config.ts

import { defineConfig } from "@graphql-hive/gateway";

export const gatewayConfig = defineConfig({
  supergraph: {
    /* Supergraph Configuration */
  },
  // By default it polls the schema registry every 10 seconds
  pollingInterval: 10_000,
});

If you use a source like Hive CDN or a custom URL as a source for the supergraph schema, CLI will automatically poll the source for changes and update the schema accordingly with 10 seconds interval. If you want to change this behavior by setting the --polling=10s flag or pollingInterval in the configuration file.

Learn more about the configuration file Learn more about the CLI flags

Proxy

Instead of serving a supergraph, you can also use Hive Gateway to proxy any existing GraphQL API. This allows you to add features such as usage reporting or persisted documents without modifying your existing GraphQL API.

When using the Gateway in proxy mode with introspection of the source schema, schema directives are not supported because they are not part of the introspection response.

This means proxy mode with introspection is not compatible with directive driven cache, auth, demand and control, or any other feature relying on directives.

Proxy GraphQL API

hive-gateway proxy https://example.com/graphql

gateway.config.ts

import { defineConfig } from "@graphql-hive/gateway";

export const gatewayConfig = defineConfig({
  proxy: {
    endpoint: "https://example.com/graphql",
  },
});

Edit on GitHub

Gateway: Supergraph schema

Supergraph

Polling

Proxy

On this page