import { Callout } from '@theguild/components'

# Apollo Gateway

[Apollo-Gateway](https://www.apollographql.com/docs/federation/v1/gateway/) is the JavaScript Apollo
Federation gateway runtime.

Hive integrates with Apollo Gateway to provide the Supergraph schema information required for
running a federated graph gateway, once all schemas are published.

```mermaid

flowchart LR
    A["Apollo Gateway
      (with Hive client)"] -. Poll supergraph .-> C
    subgraph hive [Hive]
      direction TB
      B[Registry] -. Publish supergraph .-> C["HA CDN
        (on Cloudflare)"]
    end
    A -. Report usage data .-> B

    A --> X1[GraphQL subgraph]
    A --> X2[GraphQL subgraph]
    A --> X3[GraphQL subgraph]
    X1 -.- D([Hive CLI])
    X2 -.- D
    X3 -.- D
    subgraph ci [CI/CD]
      D -- Publish schemas --> B
    end

```

## Installation

```sh npm2yarn
npm i @graphql-hive/apollo
```

<Callout type="info">
  We recommend installing Hive Client package as a direct dependency of your project, because it
  includes a runtime to send usage reports and schemas to Hive registry.
</Callout>

The `@graphql-hive/apollo` package exports a utility function called `createSupergraphManager` that
fetches the Supergraph schema from the Hive's CDN, and also a
[Apollo-Server plugin](https://www.apollographql.com/docs/apollo-server/) for reporting operations.

## Supergraph SDL from the CDN

Once you have all services schemas pushed to Hive, and available in the CDN, you can
[create a CDN Access Token and gain access to the CDN endpoint](/docs/high-availability-cdn#cdn-access-tokens).

With the endpoint and CDN access token available, you can integrate Hive with Apollo Gateway:

```ts
import { ApolloGateway } from '@apollo/gateway'
import { ApolloServer } from '@apollo/server'
import { startStandaloneServer } from '@apollo/server/standalone'
import { createSupergraphManager } from '@graphql-hive/apollo'

const gateway = new ApolloGateway({
  // Apollo Gateway will fetch Supergraph from Hive CDN
  supergraphSdl: createSupergraphManager({
    endpoint: 'HIVE_CDN_ENDPOINT',
    key: 'HIVE_CDN_KEY',
    pollIntervalInMs: 15_000
  })
})

const server = new ApolloServer({ gateway })

const { url } = await startStandaloneServer({ server })
console.log(`🚀 Server ready at ${url}`)
```

## Usage Reporting

<Callout>
  For more configuration options, such as sampling, client name and version reporting, please refer
  to the [Hive client configuration](/docs/api-reference/client#configuration) reference.
</Callout>

To enable Usage Reporting with your Apollo Gateway, you can use the Hive plugin for Apollo Server:

```ts
import { ApolloGateway } from '@apollo/gateway'
import { ApolloServer } from '@apollo/server'
import { startStandaloneServer } from '@apollo/server/standalone'
import { createSupergraphManager, useHive } from '@graphql-hive/apollo'

const gateway = new ApolloGateway({
  // Apollo Gateway will fetch Supergraph from Hive CDN
  supergraphSdl: createSupergraphManager({
    endpoint: process.env.HIVE_CDN_ENDPOINT,
    key: process.env.HIVE_CDN_KEY,
    pollIntervalInMs: 15_000
  })
})

const server = new ApolloServer({
  gateway,
  plugins: [
    useHive({
      enabled: true,
      token: 'YOUR-TOKEN',
      usage: true // add this one to report usage and operations
    })
  ]
})

const { url } = await startStandaloneServer({ server })
console.log(`🚀 Server ready at ${url}`)
```

<Callout>
  The `HIVE_CDN_ENDPOINT` variable should **NOT** include any artifact suffix (for example,
  `/supergraph`), it should be in the following format:
  `https://cdn.graphql-hive.com/artifacts/v1/TARGET_ID`
</Callout>

## Additional Resources

- [Get started with Apollo Federation and Hive guide](/docs/get-started/apollo-federation)
- [Apollo Gateway documentation](https://www.apollographql.com/docs/federation/v1/gateway/)
- [Apollo Server](https://www.apollographql.com/docs/apollo-server/)
- [`@graphql-hive/apollo` source code](https://github.com/graphql-hive/platform/tree/main/packages/libraries/apollo)
- [`HivePluginOptions` configuration reference](https://github.com/graphql-hive/platform/blob/main/packages/libraries/core/src/client/types.ts)
