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.

Consume Supergraph SDL from Hive CDN

npm i @graphql-mesh/supergraph

pnpm add @graphql-mesh/supergraph

yarn add @graphql-mesh/supergraph

bun add @graphql-mesh/supergraph

If you have a supergraph schema published to GraphQL Hive registry, you can consume it in your GraphQL Mesh gateway through Hive CDN;

sources:
  - name: Supergraph
    handler:
      supergraph:
        source: https://cdn.graphql-hive.com/SOME_UUID/sdl?ext=.graphql
        schemaHeaders:
          X-Hive-CDN-Key: SOME_TOKEN

Polling the Hive CDN

sources:
  - name: Supergraph
    handler:
      supergraph:
        source: https://cdn.graphql-hive.com/SOME_UUID/sdl?ext=.graphql
        schemaHeaders:
          X-Hive-CDN-Key: SOME_TOKEN
pollingInterval: 60_000 # Poll for the supergraph updates per 1 hour

Track your Gateway

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

npm i @graphql-mesh/plugin-hive

pnpm add @graphql-mesh/plugin-hive

yarn add @graphql-mesh/plugin-hive

bun 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.

Publish & Consume Service Schemas

GraphQL Mesh can consume GraphQL schemas from Hive CDN, and it is also possible to publish the non GraphQL sources to Hive CDN and consume them in the gateway.

We have recipes for each case below.

Consume the GraphQL source schema (Federation Subgraph or a standalone GraphQL API) from Hive CDN

If your service is originally GraphQL and published to GraphQL Hive registry, you can consume it in your GraphQL Mesh gateway through Hive CDN;

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

Publish the non-GraphQL source schema (OpenAPI, SOAP etc) 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.

npm i @graphql-mesh/cli @graphql-mesh/openapi graphql

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

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

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

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

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/sdl?ext=.graphql
        schemaHeaders:
          X-Hive-CDN-Key: SOME_BASE64

Track your non-GraphQL 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. Add GraphQL Hive transform hooks into the delegation phase to track operations done to the upstream APIs.

npm i @graphql-mesh/transform-hive

pnpm add @graphql-mesh/transform-hive

yarn add @graphql-mesh/transform-hive

bun add @graphql-mesh/transform-hive

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

Config API Reference

• enabled - - If this expression is truthy, mocking would be enabled You can use environment variables expression, for example: process.env.MOCKING_ENABLED != null One of:
  • Boolean
  • String
• token (type: String) - Access Token for Usage Reporting
• agent (type: Object) - Agent Options:
  • name (type: String)
  • logger (type: Any)
  • 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
  • sampler (type: Any)
• 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:
  • 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.

• experimental__persistedDocuments (type: Object) - Experimental persisted documents configuration See more:
  • cdn (type: Object, required) - Point to your own instance of GraphQL Hive API

Used by schema reporting and token info.: * endpoint (type: String, required) - CDN endpoint * accessToken (type: String, required) - Access Token for Persisted Documents CDN

• allowArbitraryDocuments (type: Boolean) - Whether arbitrary documents should be allowed along-side persisted documents. false by default
• cache (type: Int) - Maximum amount of operations that shall be kept in memory after being loaded from the CDN. 10 seconds by default