External Schema Composition (for Apollo Federation v2)

External Schema Composition feature allows you to build and validate GraphQL Schema outside of Hive. When enabled, Hive will send necessary information over HTTP to your endpoint and expect a composition result in return.

To make this process easier, we've implemented the actual service that you need to deploy: either as a JavaScript library, or as a Docker image that can be deployed anywhere.

⚠️

Why external composition is required for Apollo Federation v2?

As part of the Apollo Federation v2 release, Apollo changed their product license from MIT to Elastic License v2 (opens in a new tab). This means that Hive Cloud cannot use Apollo Federation v2 libraries directly, or offer Cloud services that uses the new properitey libraries internally.

To use Apollo Federation v2 with your Hive project, you have to run your own composition server and connect it to Hive.

How does it work?

💡

Your deployed external composition service needs to be available publicly, to make it possible for Hive Cloud service to communicate with it. Don't worry: we've implemented a security layer to make sure only Hive can communicate with your service.

Hive Cloud uses Cloudflare Worker to communicate with your service. This means that service's address must contain a valid hostname (not an IP address), and the port must be standard.

Integration Guide

Deploy External Composition Service

You can use our one-click deployment to deploy your External Composition Service to Heroku:

Connect to Hive

Start by enabling the External Composition for your project. To do that, go to your Hive project page, and click the Settings tab. You'll notice a "External Composition" section.

External Composition section in the project settings

Next, provide the URL of your deployed endpoint, and also set the secret you set for your service. Click Save.

If your service is available publicly and the secret matches, you should see a green checkmark next to the URL:

In case of a failure, you'll see a red cross with the reason of the failure:

Now you should be able to use the External Composition feature in your project. Publish a GraphQL schema or perform a GraphQL schema check to validate your setup.

Protocol Specification

You can use the following as reference for the expected shape of the request and response payloads.

Your external composition service will have 60s to complete the composition process, otherwise Hive server will result in a timeout.

Request

Hive will dispatch your HTTP service using POST method, with the following headers:

content-type: application/json
x-hive-signature-256 will be set the to the signature of the request body once encrypted with the secret you provided in the configuration.

The request body will contain the following information:

type SchemaService = {
  sdl: String!
  name: String!
  url: String
}
 
type RequestBody = Array<SchemaService>

Example request:

[
  {
    "sdl": "type Query { users: [String] }",
    "name": "users",
    "url": "https://api.com/users"
  },
  {
    "sdl": "extend type Query { comments: [String] }",
    "name": "comments",
    "url": "https://api.com/comments"
  }
]

Response

Hive will expect your HTTP service to respond with 200 status code and the following headers:

content-type: application/json

The reponse payload should match the following type:

type CompositionResult = CompositionSuccess | CompositionFailure
 
type CompositionSuccess = {
  type: 'success'
  result: {
    supergraph: string
    sdl: string
  }
}
 
type CompositionFailure = {
  type: 'failure'
  result: {
    errors: Array<{
      message: string
      source: 'graphql' | 'composition'
    }>
  }
}

Example response:

{
  "type": "failure",
  "result": {
    "errors": [
      {
        "message": "Type \"Query\" was defined more than once.",
        "source": "graphql"
      }
    ]
  }
}

In the source you are expected to return graphql if the error is related to the schema itself, or composition if the error is related to the composition process with other schemas.

Targets & Tokens GraphQL-Yoga