Schema reporting protocol reference

This document specifies the protocol that any GraphQL server can implement to enable automatic schema registration with the Apollo schema registry.

A reference implementation of this protocol is included in Apollo Server.

Schema reporting endpoint

Servers that implement the schema reporting protocol communicate with the following GraphQL endpoint:

https://schema-reporting.api.apollographql.com/api/graphql

All requests to this endpoint require a graph API key as authentication.

Protocol sequence

The following sections illustrate the communication sequence between a GraphQL server (hereafter referred to as the edge server) and the schema reporting endpoint (Apollo):

Diagram

Step-by-step description

1. On startup, the edge server executes the service.reportServerInfo mutation, providing an EdgeServerInfo object with the server's details as input.

   • This initial call does not include an executableSchema string.
   • If this or any other reportServerInfo request fails with a non-2xx response, the edge server should retry after 20 seconds.

2. If the mutation succeeds, Apollo responds with a ReportServerInfoResponse object. This response tells the edge server:

   • How many seconds to wait before sending the next reportServerInfo request
   • Whether the next reportServerInfo request should include the executableSchema that corresponds to the executableSchemaId provided in the previous request.

   If the mutation fails, Apollo responds with a ReportServerInfoError object. In this case, the edge server should stop reporting its schema.

   • The message field of ReportServerInfoError provides a human-readable message describing the error.
   • Correct the error and deploy a new version of your edge server to resume schema reporting.

3. Assuming success in step 2, the edge server waits the specified number of seconds, then executes the reportServerInfo mutation again.

   • This request includes a normalized executableSchema string if and only if withExecutableSchema was true in Apollo's most recent ReportServerInfoResponse.

4. Go to step 2.

Pseudocode example

val info = EdgeServerInfo(..)
val schema = normalize("type Query { .. }")
var withSchema = false

function sendReport() {
  val executableSchema = if (withSchema) null else schema
  val response = reportServerInfo(info, executableSchema)

  if (response.code) {
    throw exception
    return
  }

  withSchema = response.withExecutableSchema

  setTimeout(sendReport, response.inSeconds)
}

sendReport()

Type definitions

The schema reporting protocol uses the following GraphQL types, referred to in Protocol sequence above:

# This type's fields are documented below.
input EdgeServerInfo {
  bootId: String!
  executableSchemaId: String!
  graphVariant: String! = "current"
  libraryVersion: String
  platform: String
  runtimeVersion: String
  serverId: String
  userVersion: String
}

interface ReportServerInfoResult {
  inSeconds: Int!
  withExecutableSchema: Boolean!
}

type ReportServerInfoResponse implements ReportServerInfoResult {
  inSeconds: Int!
  withExecutableSchema: Boolean!
}

type ReportServerInfoError implements ReportServerInfoResult {
  code: ReportServerInfoErrorCode!
  inSeconds: Int!
  message: String!
  withExecutableSchema: Boolean!
}

type Mutation {
  service(id: ID!): ServiceMutation!
}

type ServiceMutation {
  reportServerInfo(
    "Only sent if previously requested i.e. received ReportServerInfoResponse with withExecutableSchema = true"
    executableSchema: String,
    info: EdgeServerInfo!
  ): ReportServerInfoResult
}

EdgeServerInfo fields

Required fields

Recommended fields

Appreciated fields 🙂

By providing these values in your requests, you'll help Apollo improve its service. For example, they'll help us identify whether a certain environment, platform, or version is causing a particular issue.

Schema normalization

Two semantically identical schemas can appear different to the schema registry, such as when those schemas list the same set of object fields in a different order. To avoid this scenario, every edge server should normalize its schema before sending it to the registry.

To normalize your schema, do all of the following:

• Apply stable sorting (such as alphabetical) to the order of all type, field, and argument definitions.
• Remove all redundant whitespace.
• Remove all comments (but not docstrings).

Note that runtime dependencies on your schema document might result in poor user experience in tracking your schema changes, or even throttling of service availability.