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

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.