Apollo-Server

You can send usage reports to the Hive registry from your Apollo-Server instance using the @graphql-hive/apollo package.

⚠️

In case you want to use Apollo-Server as a Federation gateway, please refer to the Apollo Gateway integration guide.

Installation

npm i @graphql-hive/apollo

pnpm add @graphql-hive/apollo

yarn add @graphql-hive/apollo

bun add @graphql-hive/apollo

We recommend installing Hive Client package as a direct dependency of your project, because it includes a runtime to send usage reports to the Hive registry.

The @graphql-hive/apollo package exports a Apollo-Server plugin, that can be used directly.

Configuration

A full configuration guide can be found in the “Configuration” page.

Integration

Publishing Schemas

Please use the Hive CLI to publish your GraphQL schema. Follow the CI/CD instructions for automating the process.

Usage Reporting

You can report usage to the Hive registry by using the @graphql-hive/apollo package. Depending on your GraphQL server setup the configuration might differ.

💡

For more configuration options, such as sampling, please refer to the Hive client configuration reference.

GraphQL over HTTP (default)

You can send usage reporting to Hive registry by using the usage section of the configuration:

Node.js Apollo Server S setup

import { ApolloServer } from '@apollo/server'
import { startStandaloneServer } from '@apollo/server/standalone'
import { useHive } from '@graphql-hive/apollo'
 
const testServer = new ApolloServer({
  schema,
  plugins: [
    useHive({
      enabled: true,
      token: 'YOUR-TOKEN',
      usage: true
    })
  ]
})
 
const { url } = await startStandaloneServer(testServer, {
  // Attach Node.js request to context,
  // learn more in the "Client Information" section.
  async context({ req }) {
    return { req }
  }
})
 
console.log(`Server listening on ${url}`)

This will result in all operations sent to the Apollo Server being reported to the Hive registry.

Client Information

In case you want to also associate a client name and version with any operation reported to Hive, you need to send the x-graphql-client-name and x-graphql-client-version HTTP headers for requests to the Apollo Server instance from your client. You must include both of these headers, otherwise the data will not be passed along.

Example HTTP Request with client headers

curl \
  -H "x-graphql-client-name: my-client" \
  -H "x-graphql-client-version: 1.0.0" \
  -H "content-type: application/json" \
  -H "accept: application/json" \
  -X POST \
  "http://localhost:4000/graphql" \
  -d '{"query":"{ hello }"}'

In order for the client information to be sent to the Hive registry, you need to ensure that either the req (fetch API Request), request (Node.js IncomingMessage), or headers (primitive header name to value map) property is within the context object of your server.

Whether you use req, request, or headers depends on the environment you are running your Apollo Server in. E.g. on Node.js you would add req to the context, in a Cloudflare environment, you would add the request property, and in a AWS lambda environment, you would simply add the headers property.

GraphQL over WebSocket

Apollo recommends the GraphQL over WebSocket protocol for GraphQL Subscriptions using graphql-ws. Since WebSocket requests are not HTTP requests, additional configuration to the Apollo Server WebSocket setup is required for proper usage reporting to GraphQL Hive.

The following example demonstrates how to set up the Apollo Server with graphql-ws and reporting.

Node.js Apollo Server WebSocket setup

import { createServer } from 'http'
import bodyParser from 'body-parser'
import express from 'express'
import { execute, subscribe } from 'graphql'
import { useServer } from 'graphql-ws/lib/use/ws'
import { WebSocketServer } from 'ws'
import { ApolloServer } from '@apollo/server'
import { expressMiddleware } from '@apollo/server/express4'
import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer'
import { createHive, useHive } from '@graphql-hive/apollo'
import schema from './schema'
 
const PORT = 3000
 
const app = express()
const httpServer = createServer(app)
const wsServer = new WebSocketServer({
  server: httpServer,
  path: '/graphql'
})
 
const hiveClient = createHive({
  enabled: true,
  token: 'YOUR-TOKEN',
  usage: true
})
 
const serverCleanup = useServer(
  {
    schema,
    execute: hiveClient.createInstrumentedExecute(execute),
    subscribe: hiveClient.createInstrumentedSubscribe(subscribe),
    context: context => context
  },
  wsServer
)
 
const server = new ApolloServer({
  schema,
  plugins: [
    useHive(hiveClient),
    ApolloServerPluginDrainHttpServer({ httpServer }),
    {
      async serverWillStart() {
        return {
          async drainServer() {
            await serverCleanup.dispose()
          }
        }
      }
    }
  ]
})
await server.start()
app.use(
  '/graphql',
  bodyParser.json(),
  expressMiddleware(server, {
    context: async ({ req }) => ({ req })
  })
)
 
httpServer.listen(PORT, () => {
  console.log(`🚀 Query endpoint ready at http://localhost:${PORT}/graphql`)
  console.log(`🚀 Subscription endpoint ready at ws://localhost:${PORT}/graphql`)
})

Client Information

When using the graphql-ws client, you can use the connectionParams object to forward the client information to the server.

Please make sure that you follow the GraphQL over WebSocket recipe for the server from the section above.

GraphQL over WebSocket client configuration

import { createClient } from 'graphql-ws'
 
const client = createClient({
  url: `ws://localhost:400/graphql`,
  connectionParams: {
    client: {
      name: 'my-client',
      version: '1.0.0'
    }
  }
})

Additional Resources

Schema Stitching Apollo Router