Schema registration via the Apollo CLI

If you're using an earlier version of Apollo Server or another GraphQL server that doesn't support schema reporting, you can register your schema via the Apollo CLI.

Do not use both schema reporting and the Apollo CLI to register schemas for the same graph. Doing so can cause you to register "no-op" schema changes that are semantically identical but cosmetically different. For example, automatic registration preserves a schema's comments and directives, whereas manual registration does not.

Registering a non-federated schema

1. Install the Apollo CLI if you haven't yet.

2. Decide how you'll provide your server's schema to the Apollo CLI. The CLI can either:

   • Use a .gql or .graphql file saved on your local machine, or
   • Perform an introspection query on your running server to fetch the schema

3. Run the apollo service:push command, providing the following options (documented below):

   Copy

   apollo service:push \
     --localSchemaFile=./schema.gql \ # (or --endpoint)
     --key=service:docs-example-graph:NYKgCqwfCyYPIm84WVXCdw
     --graph=docs-example-graph \
     --variant=local-development \

Registering federated schemas

In a federated architecture, each of your graph's implementing services uses the Apollo CLI to register its schema as a separate service of the same graph:

First, install the Apollo CLI if you haven't yet.

Then, do the following for each of your implementing services:

1. Obtain the following values, which are required for the apollo service:push command:

   • The URL that your federated gateway will use to communicate with the service (e.g., http://products-graphql.svc.cluster.local:4001/).
   • The name that uniquely identifies the service within your graph (e.g., products).
   • The service's schema. The Apollo CLI can either:
     • Use a .gql or .graphql file saved on your local machine, or
     • Perform an introspection query on the running service to fetch the schema

2. Run the apollo service:push command, providing the following options (documented below):

   Copy

   apollo service:push \
     --localSchemaFile=./schema.gql \ # (or --endpoint)
     --key=service:docs-example-graph:NYKgCqwfCyYPIm84WVXCdw
     --graph=docs-example-graph \
     --variant=local-development \
     --serviceName=products \
     --serviceURL=http://products-graphql.svc.cluster.local:4001/

As you register your service schemas, the schema registry attempts to compose their latest versions into a single federated schema. Whenever composition succeeds, your gateway can fetch the latest federated schema from the registry.

Registering with continuous delivery

To get the most out of Studio, you should register each update to your production schema as soon as it occurs. Consequently, schema registration should be part of your continuous delivery pipeline.

Here's a sample continuous delivery configuration for CLI-based schema registration using CircleCI:

version: 2

jobs:
  build:
    docker:
      - image: circleci/node:8

    steps:
      - checkout

      - run: npm install
      # CircleCI needs global installs to be sudo
      - run: sudo npm install --global apollo
      # Start the GraphQL server.  If a different command is used to
      # start the server, use it in place of `npm start` here.
      - run:
          name: Starting server
          command: npm start
          background: true

      # make sure the server has enough time to start up before running
      # commands against it
      - run: sleep 5

      # When running on the 'master' branch, push the latest version
      # of the schema to Apollo Studio.
      - run: |
          if [ "${CIRCLE_BRANCH}" == "master" ]; then            apollo service:push --variant=master          fi