GraphQL Gateway

Hive Gateway is the GraphQL federation Gateway and/or Proxy Gateway for your GraphQL services.

Hive Gateway is a fully open-source, MIT-licensed GraphQL router that can act as a GraphQL Federation gateway, a subgraph or a proxy gateway for any GraphQL API service.

As an alternative to Apollo Router, Hive Gateway provides a flexible, open-source solution tailored to meet the needs of modern GraphQL architectures.

It supports deployment as a standalone binary, a Docker image, or a JavaScript package, making it compatible with environments such as Node.js, Bun, Deno, Google Cloud Functions, Azure Functions, or Cloudflare Workers.

Our GraphQL API Gateway provides the following features on top of your GraphQL schema:

GraphQL Subscriptions with WebSockets, HTTP Callbacks or SSE
Automatic query and request batching to reduce the number of HTTP requests to your subgraph
JSON Web Tokens (JWT) authentication between client and gateway also between gateway and subgraph
Authorization on specific fields and types using Federation Auth directives like @authenticated and @skipAuth
Role-based Access Control (RBAC) either programmatically or with directives @requiresScope and @policy
Response Caching based on either in memory or Redis for distributed caching optionally with @cacheControl directive
Security features such as safelisting, depth limit etc
Rate Limiting on specific fields and types either programmatically or declaratively with @rateLimit directive
Prometheus and OpenTelemetry integration with fully customizable spans and attributes
Persisted Documents backed by either Hive Registry or a selfhosting storage
E2E HTTP Compression from the client to the subgraph for better performance and resource management
And more

Installation

Hive Gateway can be installed in different ways depending on your preference.

This command will download the appropriate binary for your operating system.

curl -sSL https://graphql-hive.com/install-gateway.sh | sh

You can use the official Docker image to run Hive Gateway.

docker pull ghcr.io/graphql-hive/gateway

To use the NPM package, you need to have Node.js installed in your environment. Then, you can install Hive Gateway CLI with your preferred package manager.

npm i @graphql-hive/gateway

You can also use Bun as a runtime to run the JavaScript package with the same installation steps.

Starting the Gateway

Hive Gateway supports two different modes:

GraphQL Federation. Serve a supergraph provided by a schema registry like Hive Registry, a composition tool like Apollo Rover, GraphQL Mesh or any other Federation compliant composition tool such as Apollo Rover or schema registry (Hive Registry, Apollo GraphOS)
Proxy a GraphQL API. Hive Gateway can also act as a proxy to an existing GraphQL API.

To serve a GraphQL federation Gateway, we need to point the Gateway to either a local supergraph file or a supergraph served by our schema registry. For this example, we will serve a supergraph from the Hive schema registry.

Run Apollo Federation Gateway with the Hive Gateway Binary

hive-gateway supergraph \
  http://cdn.graphql-hive.com/artifacts/v1/12713322-4f6a-459b-9d7c-8aa3cf039c2e/supergraph \
  --hive-cdn-key "YOUR HIVE CDN KEY"

Run Apollo Federation Gateway with the Hive Gateway Docker Image

docker run --rm --name hive-gateway -p 4000:4000 \
  ghcr.io/graphql-hive/gateway supergraph \
  http://cdn.graphql-hive.com/artifacts/v1/12713322-4f6a-459b-9d7c-8aa3cf039c2e/supergraph \
  --hive-cdn-key "YOUR HIVE CDN KEY"

If you installed the JavaScript package, you can use npx for running the CLI.

Run Apollo Federation Gateway with npx

npx hive-gateway supergraph \
  http://cdn.graphql-hive.com/artifacts/v1/12713322-4f6a-459b-9d7c-8aa3cf039c2e/supergraph \
  --hive-cdn-key "YOUR HIVE CDN KEY"

In order to proxy a GraphQL API, we need to provide the URL of the API when starting our Gateway. Optionally, we can also provide a schema file from either a local file or a schema registry, which will be used instead of instrospecting the proxied API.

Run Proxy Gateway with the Hive Gateway Binary

hive-gateway proxy https://localhost:3000/graphql \
  --hive-cdn-endpoint http://cdn.graphql-hive.com/artifacts/v1/12713322-4f6a-459b-9d7c-8aa3cf039c2e/sdl \
  --hive-cdn-key "YOUR HIVE CDN KEY"

Run Proxy Gateway with the Hive Gateway Binary

docker run --rm --name hive-gateway -p 4000:4000 \
  ghcr.io/graphql-hive/gateway proxy https://localhost:3000/graphql \
  --hive-cdn-endpoint http://cdn.graphql-hive.com/artifacts/v1/12713322-4f6a-459b-9d7c-8aa3cf039c2e/sdl \
  --hive-cdn-key "YOUR HIVE CDN KEY"

Run Proxy Gateway with the Hive Gateway Binary

npx hive-gateway proxy https://localhost:3000/graphql \
  --hive-cdn-endpoint http://cdn.graphql-hive.com/artifacts/v1/12713322-4f6a-459b-9d7c-8aa3cf039c2e/sdl \
  --hive-cdn-key "YOUR HIVE CDN KEY"

By default, Hive Gateway will start a server on port 4000. You can customize that behavior. For that please refer to our Gateway documentation.

Configuration File

The Hive Gateway config file gateway.config.ts is used for enabling additional features such as authorization, authentication caching, rate limiting, and more. The recommended language for the configuration file is TypeScript.

We can provide the CLI configuration parameters, also via the configuration file.

gateway.config.ts

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

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

Hive Gateway will automatically load the default config file and apply the settings.

Run Proxy Gateway with the Hive Gateway Binary using configuration file

hive-gateway supergraph

For docker, we need to mount the configuration file into the container.

Run Proxy Gateway with the Hive Gateway Binary

docker run --rm --name hive-gateway -p 4000:4000 \
  -v $(pwd)/gateway.config.ts:/gateway/gateway.config.ts \
  ghcr.io/graphql-hive/gateway supergraph

Run Proxy Gateway with the Hive Gateway Binary

npx hive-gateway supergraph

gateway.config.ts

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

export const gatewayConfig = defineConfig({
  proxy: {
    endpoint: "http://localhost:3000/graphql",
  },
});

Hive Gateway will automatically load the default config file and apply the settings.

Run Proxy Gateway with the Hive Gateway Binary using configuration file

hive-gateway proxy

For docker, we need to mount the configuration file into the container.

Run Proxy Gateway with the Hive Gateway Binary

docker run --rm --name hive-gateway -p 4000:4000 \
  -v $(pwd)/gateway.config.ts:/gateway/gateway.config.ts \
  ghcr.io/graphql-hive/gateway proxy https://localhost:3000/graphql \
  --hive-cdn-endpoint http://cdn.graphql-hive.com/artifacts/v1/12713322-4f6a-459b-9d7c-8aa3cf039c2e/sdl \
  --hive-cdn-key "YOUR HIVE CDN KEY"

Run Proxy Gateway with the Hive Gateway Binary

npx hive-gateway proxy

Next steps

After learning the first steps of Hive Gateway, you can explore the following topics.

Set up Usage Reporting Set up Persisted Documents

Edit on GitHub

Installation

Starting the Gateway

Configuration File

Next steps

On this page