---
title: High-Availability CDN
---


import { Callout } from "@hive/design-system/hive-components/callout";
import { Image } from "@hive/design-system/image";

import cdnTokenImage from "./cdn_token.png";

The Hive Cloud service leverages the
[CloudFlare Global Network](https://www.cloudflare.com/network/) to deliver your GraphQL schema and
schema metadata. This means that your schema will be available from the nearest location to your
GraphQL gateway, with [amazing uptime](https://www.cloudflare.com/business-sla/), regardless of
Hive's status. This ensures that everything required for your GraphQL API and tooling around it is
always available, and reduces the risk of depending on Hive as a single point of failure.

## CDN Mirrors

To provide an even higher level of availability, Hive offers two CDN endpoints:

* `https://cdn.graphql-hive.com` (main): Built on top of Cloudflare, a fast and reliable global
  network.
* `https://cdn-mirror.graphql-hive.com` (mirror): An exact replica of the main CDN, built on top of
  AWS (DNS, networking, and runtime). It serves as a fallback in the case of a Cloudflare outage.

We recommend using the main CDN endpoint and configuring your systems to fall back to the mirror
endpoint in case of any issues. Both endpoints are functionally identical, and share the same
underlying storage and access tokens. Hive SDKs provide the option to configure a dual endpoint and
have a built-in [circuit breaker](https://en.wikipedia.org/wiki/Circuit_breaker_design_pattern) that
ensures a smooth experience in case the main CDN becomes unavailable.

For more on configuring your Gateway and SDKs for high availability, see
[Running with Hive Console in Production](/docs/schema-registry/high-availability-resilience).

```mermaid

flowchart LR
    A["GraphQL Gateway"] -.-> C["Highly available GraphQL schema
      on Cloudflare or AWS"]
    B["Frontend tooling
        (e.g. GraphQL code generator)"] -.-> C

```

<Callout type="info">
  The High-Availability CDN is available only in Hive Cloud, and not available
  for the self-hosted version. For the self-hosted version you can expose the
  CDN route handlers via the Hive API. [Learn
  more](/docs/schema-registry/self-hosting/cdn-artifacts).
</Callout>

Currently you can access the single services, merged schema, supergraph, metadata (e.g. GraphQL Mesh
artifacts) and persisted documents via the CDN.

## CDN Access Tokens

To get started with Hive's CDN access, you'll need to create a CDN token for your target (see
[Target & Tokens](/docs/schema-registry/management/targets#cdn-access-tokens)).

<Callout>
  The CDN access token is considered a secret and should not be shared with
  anyone else. If a CDN access token is compromised, you can [revoke it from the
  target's Settings
  page](/docs/schema-registry/management/targets#revoking-a-cdn-access-token),
  and create a new token.
</Callout>

To use your CDN access token, go to your target's page on Hive's dashboard and click on the
**Connect to CDN** button.

<Image alt="CDN Token Form" className="mt-10 max-w-2xl rounded-lg drop-shadow-md" src={cdnTokenImage} />

## Artifacts stored in the CDN

You can access the GraphQL schema (SDL), services information (for both Schema-Stitching and Apollo
Federeation), Supergraph (for Apollo Federation) and Hive schema metadata via the CDN.

<Callout>
  All examples use `https://cdn.graphql-hive.com` but you can use
  `https://cdn-mirror.graphql-hive.com` as a drop-in replacement.
</Callout>

### GraphQL schema (SDL)

Also called the API Schema--this is the public-facing contract. It is what your clients would see
when they interact with your API.

```bash
curl -v -H 'X-Hive-CDN-Key: CDN_ACCESS_TOKEN' \
  "https://cdn.graphql-hive.com/artifacts/v1/TARGET_ID/sdl"
```

### List of Services

The list of services is a JSON representation of all the GraphQL services in your target. This can
be used for tooling that lives outside of Hive that requires a list of services and/or their
internal SDL.

```bash
curl -v -H 'X-Hive-CDN-Key: CDN_ACCESS_TOKEN' \
  "https://cdn.graphql-hive.com/artifacts/v1/TARGET_ID/services"
```

### Supergraph

<Callout>
  This artifact is only available for Apollo Federation projects.
</Callout>

This is the internal representation of your API that includes routing information and other metadata
that's required for a federated gateway to handle requests and route them properly. This is not
intended for clients because it reveals your internal microservice architecture.

```bash
curl -v -H 'X-Hive-CDN-Key: CDN_ACCESS_TOKEN' \
  "https://cdn.graphql-hive.com/artifacts/v1/TARGET_ID/supergraph"
```

Further reading:

* [Get started with Hive and Apollo Federation](/docs/schema-registry/get-started/apollo-federation)
* [Integrating Hive CDN with Apollo Gateway](/docs/other-integrations/apollo-gateway)
* [Integrating Hive CDN with Apollo Router](/docs/other-integrations/apollo-router)

### Hive Metadata

<Callout>
  This artifact is only available for Single and Schema-Stitching projects. To
  provide metadata in a federated system, consider using
  [directives](/docs/api-reference/link-specifications#meta).
</Callout>

```bash
curl -v -H 'X-Hive-CDN-Key: CDN_ACCESS_TOKEN' \
  "https://cdn.graphql-hive.com/artifacts/v1/TARGET_ID/metadata"
```

## Versioned Artifacts

You can fetch artifacts for a specific schema version using the versioned endpoints. This is useful
for retrieving historical schemas or ensuring consistent deployments.

### Fetching Artifacts by Version ID

Use the `/version/:versionId` path segment to fetch artifacts for a specific version:

```bash
curl -L -H 'X-Hive-CDN-Key: CDN_ACCESS_TOKEN' \
  "https://cdn.graphql-hive.com/artifacts/v1/TARGET_ID/version/VERSION_ID/sdl"
```

All artifact types are supported with versioned endpoints:

* `/artifacts/v1/TARGET_ID/version/VERSION_ID/sdl`
* `/artifacts/v1/TARGET_ID/version/VERSION_ID/services`
* `/artifacts/v1/TARGET_ID/version/VERSION_ID/supergraph`
* `/artifacts/v1/TARGET_ID/version/VERSION_ID/metadata`

### Versioned Contract Artifacts

For Federation projects with contracts, you can fetch versioned contract artifacts:

```bash
curl -L -H 'X-Hive-CDN-Key: CDN_ACCESS_TOKEN' \
  "https://cdn.graphql-hive.com/artifacts/v1/TARGET_ID/version/VERSION_ID/contracts/CONTRACT_NAME/supergraph"
```

### Schema Version ID Header

Every CDN artifact response includes the `x-hive-schema-version-id` header, which contains the
version ID of the schema being served. This header is present in responses from both latest and
versioned endpoints.

```bash copy=false title="Example response"
curl -v -L -H 'X-Hive-CDN-Key: CDN_ACCESS_TOKEN' \
  "https://cdn.graphql-hive.com/artifacts/v1/TARGET_ID/sdl"

abc123-def456-789 < x-hive-schema-version-id:
"a1b2c3d4" < etag:
```

You can use this header to:

* Track which schema version your gateways are currently running
* Correlate schema versions with deployments and logs
* Fetch the exact same schema version later using the versioned endpoint

## How it works

Every time you successfully publish a GraphQL schema to the schema registry, Hive replicated the
schema and its metadata, and push it to the CDN to make it globally available through a secured
channel.

The artifacts are stored on an S3 compatible bucket. In order to load them, you need to send a `GET`
request to the CDN URL with the `X-Hive-CDN-Key` header.

```mermaid
sequenceDiagram;
    participant Consumer
    participant CDN
    participant CDN Storage

Consumer->>CDN: Request GET /v1/artifact/HIVE_TARGET_ID/sdl
CDN->>Consumer: Responds with 302 storage URL
Consumer->>CDN Storage: GET: storage URL
CDN Storage->>Consumer: Sends Artifact
```

Here's an example for

```bash copy=false title="Example curl Request for accessing SDL"
curl -v -H 'X-Hive-CDN-Key: CDN_ACCESS_TOKEN' \
  https://cdn.graphql-hive.com/v1/HIVE_TARGET_ID/sdl

/artifacts/v1/c7ce447c-f5e6-4f13-87b8-d3051ba3fc45/sdl > GET
302 < Found
location < Header: https://6d5bc18cd8d13babe7ed321adba3d8ae.r2.cloudflarestorage.com/artifacts/c7ce447c-f5e6-4f13-87b8-d3051ba3fc45/sdl
Found.
```

In case the request was successful (correct authorization header was provided and the artifact
exists). The CDN will respond with status code `302`. You can now access the artifact via the
provided URL in the `location` header. The link is valid for 60 seconds.

Adding `-L` to the `curl` command will follow the redirect and return the artifact itself:

```bash copy=false title="Example curl Request for accessing SDL"
curl -L -H 'X-Hive-CDN-Key: CDN_ACCESS_TOKEN' \
  https://cdn.graphql-hive.com/v1/HIVE_TARGET_ID/sdl

type Query {
ping: String
}%
```

## CDN Caching

The CDN service accepts the [`ETag`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag)
and [`If-None-Match`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-None-Match)
headers.

Every successful response from the CDN service (`200 OK`) contains the `ETag` header with a
checksum. If you send the same checksum in the `If-None-Match` header, the CDN service will return
`304 Not Modified`, but only if the data hasn't changed. If the data has changed, the CDN service
will return `200 OK` with the new data and new `ETag` header.

Using `ETag` and `If-None-Match` helps to prevent unnecessary data transfer.

The [`@graphql-hive/core`](/docs/api-reference/client) package uses this
feature to save bandwidth and improve performance.

## CDN Hosts

Your company might have strict rules for accessing external services. In case you need to allow-list
hosts for the CDN service, you can use the following list.

```bash
cdn.graphql-hive.com
cdn-mirror.graphql-hive.com
```