GraphQL Hive Integration

GraphQL Hive is a schema registry, monitoring and analytics tool for your GraphQL API, and it is possible to integrate your GraphQL Mesh application to GraphQL Hive by using the dedicated plugins and transforms.

Track your Gateway

You can connect your GraphQL Mesh gateway to GraphQL Hive to GraphQL Hive registry to track changes on the unified schema and monitor the operations done by the clients.

yarn add @graphql-mesh/plugin-hive

plugins:
  - hive:
      token: '{env.HIVE_TOKEN}'

Publish and check the gateway schema

Everytime you build GraphQL Mesh gateway, you can find human-readable SDL version of your schema under .mesh/schema.graphql. You can configure your CI to publish and check your schema automatically by using Hive CLI.

Learn more about managing the schema using GraphQL Hive CLI (opens in a new tab)

Track your sources

GraphQL Mesh creates GraphQL APIs from non GraphQL APIs, and it is still possible to register these to GraphQL Hive as a regular GraphQL API. GraphQL Hive transform hooks into the delegation phase to track operations done to the upstream APIs.

yarn add @graphql-mesh/transform-hive

sources:
  - name: FooService
    handler:
      openapi:
        source: ./openapi.json
    transforms:
      - hive:
          token: '{env.MYOAS_HIVE_TOKEN}'

Publish the source schema seperately then consume it in the gateway

Let's say you have different repos on each service and you want to publish the schema on these repos, and keep the configuration for these services there. And the gateway will consume these schemas and merge them together.

Step 1: Create a project for the service

Create a project for the service, and get an active token for this gateway.

Learn more about getting tokens from Hive (opens in a new tab)

Step 2: Setup Mesh CLI on the service repo

Let's say you have an OpenAPI service on that repo then install the following packages in this case;

yarn add @graphql-mesh/cli @graphql-mesh/openapi graphql

Then configure the source in .meshrc.yml file;

sources:
  - name: FooService
    handler:
      openapi:
        source: ./openapi.yml

Step 3: Publish the service schema

You need to install GraphQL Hive CLI and configure it with the token you already created before.

See how to install Hive CLI (opens in a new tab)

Then you need to run mesh build like you do on the gateway to generate the schema, so GraphQL Hive CLI can publish it.

Finally, you can publish the schema hive schema:publish .mesh/sources/FooService/schema.graphql

Step 4: Create Hive CDN URL and token for the service

Go to the service project and click Connect on the right top of the page. Copy the URL and header then paste it to the .meshrc.yml file.

sources:
  - name: FooService
    handler:
      openapi:
        # URL needs to have `.graphql` extension to tell the handler it is a GraphQL Schema
        source: https://cdn.graphql-hive.com/SOME_UUID?ext=.graphql
        schemaHeaders:
          X-Hive-CDN-Key: SOME_BASE64

Config API Reference

• token (type: String, required) - Access Token
• agent (type: Object) - Agent Options:
  • timeout (type: Int) - 30s by default
  • maxRetries (type: Int) - 5 by default
  • minTimeout (type: Int) - 200 by default
  • sendInterval (type: Int) - Send reports in interval (defaults to 10_000ms)
  • maxSize (type: Int) - Max number of traces to send at once (defaults to 25)
• usage (type: Object) - Collects schema usage based on operations:
  • clientInfo (type: Object) - Extract client info from GraphQL Context:
    • name (type: String) - Extract client name Example: {context.headers['x-client-name']}
    • version (type: String) - Extract client version Example: {context.headers['x-client-version']}
  • max (type: Int) - Hive uses LRU cache to store info about operations. This option represents the maximum size of the cache. Default: 1000
  • ttl (type: Int) - Hive uses LRU cache to store info about operations. This option represents the maximum age of an unused operation in the cache. Default: no ttl
  • exclude (type: Array of String) - A list of operations (by name) to be ignored by Hive.
  • sampleRate (type: Float) - Sample rate to determine sampling. 0.0 = 0% chance of being sent 1.0 = 100% chance of being sent Default: 1.0
  • processVariables (type: Boolean) - (Experimental) Enables collecting Input fields usage based on the variables passed to the operation. Default: false
• reporting (type: Object) - Schema reporting:
  • author (type: String, required) - Author of current version of the schema
  • commit (type: String, required) - Commit SHA hash (or any identifier) related to the schema version
  • serviceName (type: String)
  • serviceUrl (type: String)
• selfHosting (type: Object) - Options for self-hosting See more (opens in a new tab):
  • graphqlEndpoint (type: String, required) - Point to your own instance of GraphQL Hive API

Used by schema reporting and token info.

• applicationUrl (type: String, required) - Address of your own GraphQL Hive application

Used by token info to generate a link to the organization, project and target.

• usageEndpoint (type: String) - Point to your own instance of GraphQL Hive Usage API

Used by usage reporting.