4. Publishing to the registry
5m

Overview

In this lesson, we will:

  • Create a with a in
  • Publish a to the schema registry using the

Creating a graph in GraphOS Studio

Let's start by spinning up a new .

  1. Open up a new browser window and go to GraphOS Studio.

Check your plan: Part of this course covers the self-hosted router, which requires a GraphOS Enterprise plan. You can still follow along if your organization is on a different plan, but you won’t be able to complete certain hands-on tasks. You can also test out this functionality by signing up for a free Enterprise trial.

If you haven't created a in Studio before now, you'll be prompted to do so.

https://studio.apollographql.com

Studio - new organization, create new graph

Otherwise, we can create a new by clicking the + Create New Graph button in the upper right corner.

https://studio.apollographql.com

Studio, create new graph

We'll give our a descriptive title (we've chosen the name "MusicMatcher"), keep the default settings for Graph Architecture as "", then click Next.

https://studio.apollographql.com

Studio, create new graph modal options

If you don't see the modal above, you may be on the wrong plan.

We should now see a new modal with instructions for publishing our schema.

https://studio.apollographql.com

Studio, publish schema modal

Publishing the soundtracks schema

To publish our soundtracks schema to our new , we'll use the . Rover lets us connect to our graph from the command line and publish schemas, but it needs a couple of pieces of data first:

  • APOLLO_KEY: Your 's API key, used to interact with a single in . It starts with something like "service:your-graph-name". Note that this is different from your personal API key, which we used to authenticate in the first lesson, and grants you partial access to every in the organization you belong to.
  • APOLLO_GRAPH_REF: The erence (or graph ref) for our , which we'll use to tell where to publish our . A graph ref starts with the graph's ID, followed by an @ symbol, followed by the .

We'll use these values again when we run the , so we can store them in a new file we'll add to the router directory called .env.

Let's create that file now.

πŸ“¦ Odyssey.MusicMatcher
┣ πŸ“‚ Router
┃ ┣ πŸ“„ router-config.yaml
┃ ┣ πŸ“„ .env

Storing variables

  1. First, make sure that the Supergraph Pipeline Track dropdown is set to Federation 2.5 Supergraph. This specifies that our should be built using the same federation version as our schemas. The Hot Chocolate we're using only supports 2.5 at this time.

    https://studio.apollographql.com

    Studio, supergraph pipeline trackl

    Make sure you're on the Schema Document tab, not the Introspection tab.

  2. Below, take a little peek at the command for publishing a . We'll be running this command shortly, but for now, we're more interested in the APOLLO_KEY environment variable here.

    APOLLO_KEY=your-graphs-apollo-key \
    rover subgraph publish your-graph-name@current \
    --name products --schema ./products-schema.graphql \
    --routing-url http://products.prod.svc.cluster.local:4001/graphql
  3. Click on the eye icon on the code block to reveal the full value of APOLLO_KEY. Copy APOLLO_KEY and its value to your clipboard, then paste it into Router/.env.

    Router/.env
    APOLLO_KEY=your-graphs-apollo-key
  4. Now let's go back to Studio to get our . The value we're looking for appears in the same code block, directly after the " publish" part of the command. We'll save this value as an environment variable as well, but we can access it anytime from our graph's home page.

    Router/.env
    APOLLO_KEY=your-graphs-apollo-key \
    rover subgraph publish your-graph-name@current \
    --name products --schema ./products-schema.graphql \
    --routing-url http://products.prod.svc.cluster.local:4001/graphql
  5. In your Router/.env file, add a new line and set your APOLLO_GRAPH_REF environment variable:

    Router/.env
    APOLLO_KEY=your-graphs-apollo-key
    APOLLO_GRAPH_REF=your-graph-name@current

Warning: For security, environment variables should never be committed to version control. For this reason, this project includes a .gitignore file which specifies that the .env file should be ignored when committing code changes to a repository.

We've got the values we need to publish our !

The rover subgraph publish command

has a command ready to help us with this important task: rover subgraph publish. This command publishes the latest version of a single to the schema registry.

rover subgraph publish <APOLLO_GRAPH_REF> \
--name <SUBGRAPH NAME> \
--schema <SCHEMA FILE PATH> \
--routing-url <ROUTING URL>

To use this command, we need the for the we want to publish to and the following command line options:

OptionWhat is it?
--nameWhat we want to call our subgraph
--schemaThe relative path to our subgraph's schema file
--routing-urlThe URL where our subgraph runs (locally, for now)

Note: If your soundtracks server is not already running, boot it up now!

We'll fill in these options with the details of our soundtracks .

  1. Bounce back to the terminal and make sure we're in the root directory for the project.

  2. Now let's type out the rover subgraph publish command, and paste in the value of our APOLLO_GRAPH_REF environment variable.

    For the name option, we'll pass in soundtracks.

    For the schema option, we'll pass the relative path to our schema.graphql file.

    And for the routing-url option, we'll pass in http://localhost:5059/graphql, where our server is running.

    rover subgraph publish <APOLLO_GRAPH_REF> \
    --name soundtracks \
    --schema schema.graphql \
    --routing-url http://localhost:5059/graphql

    Note: We've used the \ character in this command to improve legibility by putting each command-line option on its own line. If you choose to type the entire publish command on a single line, you don't need to include the \.

  3. You'll see the following message:

    The host `localhost` is not routable via the public internet.
    Continuing the publish will make this subgraph reachable in local environments only.
    Would you still like to publish? [y/N]

    Type in y to allow it. We're in tutorial land and working in local environments for now! In a production environment, we would incorporate this command into CI/CD and deploy it to be accessible outside of our own computers.

    Note that you'll see this message after every publish command that points to a localhost URL.

    If all is well in the world, we should see a message confirming that the has been published and the has been updated!

Checking the results in GraphOS Studio

Let's go back to Studio and have a look at "See schema changes".

https://studio.apollographql.com

Studio - see schema changes

This takes us to a new page called Launches. A is the process that runs every time we make a change to our . We'll take a closer look at launches in an upcoming lesson.

https://studio.apollographql.com

Studio - Launches page

For now let's click on the Schema tab in the sidebar.

Schema Reference

The Schema Reference page lets us see all the types and in our . That's right, even though we've only published one so far, we already have a supergraph schema!

https://studio.apollographql.com

Studio - schema reference

We see that our 's Query type includes the two : featuredPlaylists and playlist(id). Each is annotated with its description, any it requires, and which it belongs to.

Let's take a closer look at that . Click on the SDL tab at the top of the Schema page. Here we can see details about our published , along with two additional schemas.

The API schema is the API that gets exposed to your clients. It cleanly and logically represents the combination of your . (We won't worry about this schema for now.)

https://studio.apollographql.com

Studio - API schema SDL

The Supergraph schema is used by the like a map, to define how incoming can be divided up among the underlying . We only have one at the moment, so all in an operation will be routed over to the soundtracks .

https://studio.apollographql.com

Studio - supergraph schema SDL

Practice

What does the rover subgraph publish command do?

Key takeaways

  • We can use the rover subgraph publish command from the to publish our to .
  • The consolidates all the types and across our published . It also includes extra to help the determine which subgraphs can resolve each field.

Up next

We're still missing an important piece of the architecture: the .

Previous

Share your questions and comments about this lesson

This course is currently in

beta
. Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.