/
Launch Apollo Studio

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):

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

The URL of the running service to perform an introspection query on.

Provide this only if the CLI should obtain your schema via introspection.

--localSchemaFile

The path of the schema file to register.

Provide this only if the CLI should obtain your schema via a local file.

--key

The graph API key that the CLI should use to authenticate with the schema registry.

By default, the CLI uses the value of the APOLLO_KEY environment variable.

--graphThe name of your graph in Apollo Studio (e.g., docs-example-graph)
--variant

The variant of your graph to register the schema with.

The default value is current.

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:

--serviceName=Products
--serviceName=Reviews
--serviceName=Inventory
Gateway
Products service
Reviews service
Inventory service
Apollo Schema Registry

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):

    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/
NameDescription
--endpoint

The URL of the running service to perform an introspection query on.

Provide this only if the CLI should obtain your schema via introspection.

--localSchemaFile

The path of the schema file to register.

Provide this only if the CLI should obtain your schema via a local file.

--key

The graph API key that the CLI should use to authenticate with the schema registry.

By default, the CLI uses the value of the APOLLO_KEY environment variable.

--graphThe name of your graph in Apollo Studio (e.g., docs-example-graph)
--variant

The variant of your graph to register the schema with.

The default value is current.

--serviceNameThe service's unique name in your federated graph (e.g., products).
--serviceURLThe URL that your federated gateway will use to communicate with the service.

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
Edit on GitHub