App Deployments

App deployments are a way to group and publish your GraphQL operations as a single app version to the Hive Registry. This allows you to keep track of your different app versions, their operations usage, and performance.

Making better decisions about:

• Which operations are being used by what app client version (mobile app, web app, etc.)
• Which team or developer is responsible for a specific operation and needs to be contacted for Schema change decissions

Furthermore, it allows you to leverage persisted documents (also knows as trusted documents or persisted queries) on your GraphQL Gateway or server, which provides the following benefits:

• Reduce payload size of your GraphQL requests (reduce client bandwidth usage)
• Secure your GraphQL API by only allowing operations that are known and trusted by your Gateway

Create an App Deployment

To create an app deployment, you need to have the Hive CLI installed and authenticated with your Hive target, on which you want to deploy your app.

In addition you must have a JSON file containing a set of persisted documents generated by a tool such as GraphQL Code Generator.

{
  "d9a00ec0c1ce": "query UsageEstimationQuery($input: UsageEstimationInput!) { __typename usageEstimation(input: $input) { __typename operations } }",
  "b8d98e796421": "mutation GenerateStripeLinkMutation($selector: OrganizationSelectorInput!) { __typename generateStripePortalLink(selector: $selector) }"
}

These persisted documents define all the possible operations that your app can execute against your GraphQL API.

As long as the app is using these persisted documents is active, any change of the GraphQL API that alters the GraphQL schema as used by any of the persisted documents would break that specific app version and therefore be an unsafe/breaking change.

Note: The GraphQL operations being uploaded must pass validation against the target schema. Otherwise, the app deployment creation will fail.

Once these pre-requisites are met, you can create an app deployment by running the following command:

hive app:create --name "my-app" --version "1.0.0" persisted-operations.json

The parameters --name and --version are mandatory and uniquily identify your app deployment.

An app deployment is uniquely identified by the combination of the name and version parameters for each target.

After creating an app deployment, it is in the pending state. That means you can view it on the Hive App UI.

Navigate to the Target page on the Hive Dashboard and click on the Apps tab to see it.

By clicking on the app deployments name, you can navigate to the app deployment details page, where you can see all the GraphQL operations that are uploaded as part of this app deployment.

Publish an App Deployment

A app deployment will be in the pending state until you publish it. By publishing the app deployment, the persisted documents will be available via the Hive CDN and can be used by your Gateway or GraphQL API for serving persisted documents to your app.

To publish an app deployment, you can run the following command. Make sure you utilize the same --name and --version parameters as you used when creating the app deployment.

hive app:publish --name "my-app" --version "1.0.0"

After publishing the app deployment, the persisted documents, the status of the app deployment on the Hive dashboard will change to active.

Persisted Documents on GraphQL Server and Gateway

Persisted documents can be used on your GraphQL server or Gateway to reduce the payload size of your GraphQL requests and secure your GraphQL API by only allowing operations that are known and trusted by your Gateway.

Hive serves as the source of truth for the allowed persisted documents and provides a CDN for fetching these documents as they are requested.

npm i -D @graphql-hive/yoga

pnpm add -D @graphql-hive/yoga

yarn add --dev @graphql-hive/yoga

bun add --dev @graphql-hive/yoga

import { createYoga } from 'graphql-hive'
import { useHive } from '@graphql-hive/yoga'
import schema from './schema.js'
 
const yoga = createYoga({
  schema,
  plugins: [
    useHive({
      enabled: false
      experimental__persistedDocuments: {
        cdn: {
          // replace <target_id> and <cdn_access_token> with your values
          endpoint: 'https://cdn.graphql-hive.com/<target_id>',
          accessToken: '<cdn_access_token>'
        }
      }
    })
  ]
})

npm i -D @graphql-hive/apollo

pnpm add -D @graphql-hive/apollo

yarn add --dev @graphql-hive/apollo

bun add --dev @graphql-hive/apollo

import { ApolloServer } from '@apollo/server'
import { useHive } from '@graphql-hive/apollo'
import schema from './schema.js'
 
const server = new ApolloServer({
  schema,
  plugins: [
    useHive({
      experimental__persistedDocuments: {
        cdn: {
          // replace <target_id> and <cdn_access_token> with your values
          endpoint: 'https://cdn.graphql-hive.com/<target_id>',
          accessToken: '<cdn_access_token>'
        }
      }
    })
  ]
})

import { defineConfig } from '@graphql-mesh/serve-cli'
 
export default defineConfig({
  hive: {
    // The endpoint of CDN
    endpoint: 'https://cdn.graphql-hive.com/<target_id>/supergraph',
    experimental__persistedDocuments: {
      cdn: {
        // replace <target_id> and <cdn_access_token> with your values
        endpoint: 'https://cdn.graphql-hive.com/<target_id>',
        accessToken: '<cdn_access_token>'
      }
    }
  }
})

GET https://cdn.graphql-hive.com/<target_id>/apps/<app_name>/<app_version>/<document_hash>

curl \
  -L \
  -H 'X-Hive-CDN-Key: CDN_ACCESS_TOKEN' \
  https://cdn.graphql-hive.com/<target_id>/apps/<app_name>/<app_version>/<document_hash>

Sending Persisted Document Requests from your App

Once you have the persisted documents available on your GraphQL server or Gateway, you can send a GraphQL request with the persisted document ID following the GraphQL over HTTP specification.

POST /graphql
Content-Type: application/json
{
  "documentId": "<app_name>/<app_version>/<document_hash>",
}

Example curl request:

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"documentId": "<app_name>~<app_version>~<document_hash>"}' \
  http://localhost:4000/graphql

Continous Deployment (CD) Integration

We recommend integrating the app deployment creation and publishing into your CD pipeline for automating the creationg and publishing of app deployments.

Usually the following steps are performed.

Since the application will be configured to send requests with the persisted document ID, we need to ensure that these documents are available on the Hive CDN before deploying the application.

Extracting the persisted documents usually happens during the build step of your application. E.g. if you are using GraphQL Code Generator with the client preset or Relay, the persisted document JSON mapping is generated as an artifact.

In your CLI pipeline, you can then use the Hive CLI (or Hive CLI docker container) to create and publish the app deployment.

After that, you can deploy your application with confidence.

Tools like GitHub Actions, Pulumni, or Terraform can be used to model this flow. We use it ourselves for deploying the GraphQL Hive Dashboard using Pulumni.