On this page

Apollo-Server

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

Installation

npm i @graphql-hive/apollo

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.

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: {
        target: "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>",
      },
    }),
  ],
});

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 client information HTTP headers for requests to the Apollo Server instance from your client. Those are x-graphql-client-name (or graphql-client-name) and x-graphql-client-version (or graphql-client-version). 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 }"}'

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 Hive Console.

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: {
    target: "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>",
  },
});

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