Publishing our schemas

8. Publishing our schemas

Overview

We're well on our way with the accounts subgraph! We've defined our User interface and the Host and Guest entities in both subgraphs. It's time to get these changes composed into the supergraph!

In this lesson, we will:

Learn about how fields can (and cannot) be shared between subgraphs
Publish our changes to the registry and test our updated supergraph

Publishing our schema changes

We've made a lot of changes to our two subgraph schemas. Let's check to see if our supergraph schema still composes.

Note: We're going to publish our current subgraph schemas to the registry, which will take care of composition for us. However, when working in a production environment, you'll want to first test these schema changes using a combination of schema checks and variants integrated into your CI pipeline. We'll dive into these concepts in Voyage III, the next course of the series.

To publish our schema changes in the accounts subgraph, we'll use the rover subgraph publish command with the corresponding values. Since this is the first time we're publishing the accounts subgraph, we'll also need to add a routing-url. (Our subgraph is running locally, so make sure you specify http and not https!)

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

Remember to replace the <APOLLO_GRAPH_REF> value with your own, and take note that we're running this command in the root directory of our project!

Wait - what are these errors in the terminal? Here's an example of one of the errors we see after running the command.

INVALID_FIELD_SHARING: Non-shareable field "Host.name" is resolved from multiple subgraphs:
it is resolved from subgraphs "accounts" and "monolith" and defined as non-shareable in all of them

What we're seeing is an example of invalid field sharing.

Invalid field sharing

Let's talk about what this error means, and what we can do to fix it!

We published our accounts schema to Studio, which triggered composition. But right now, the latest version of the monolith subgraph that Studio is aware of is the one without our most recent changes. As far as it knows, the monolith subgraph still includes these accounts-related fields on Host and Guest!

As a result, the composition process discovered a number of fields that are defined in both of the subgraphs Studio knows about. This causes an error because by default, a field can't be defined or resolved by more than one subgraph.

If we did want a field to be defined or resolved by multiple subgraphs, we'd need to enable this explicitly by using the @shareable directive.

The `@shareable` directive

The @shareable directive enables multiple subgraphs to resolve a particular object field (or set of object fields).

For example, if we wanted to allow both the monolith and accounts subgraphs to resolve the Host.name field, we could leave the definitions in both and mark the field with @shareable.

type Host implements User @key(fields: "id") {
  # ... other Host fields
  name: String @shareable
}

Note: You'd also need to add the @shareable directive to the Federation 2 schema definition imports in the subgraph, as detailed in the docs.

Adding the @shareable directive to both field definitions would take care of the build error.

However, in our case, we don't want to do this! For Airlock, we've decided that only the accounts subgraph will be responsible for these fields. Fortunately, we can fix this error by publishing our changes to the monolith subgraph. This will bring Studio up to date on our decision to relocate accounts-related fields to the accounts subgraph.

Publishing the `monolith` subgraph

Let's take care of this step now, and clear up those errors in the terminal! Run the following rover subgraph publish command for the monolith subgraph, swapping in the values specific to your graph.

rover subgraph publish <APOLLO_GRAPH_REF> \
--schema ./monolith/schema.graphql \
--name monolith

If there's an error in the terminal, have no fear! These troubleshooting tips cover a few of the most common scenarios we might encounter when publishing our subgraph.

`INVALID_FIELD_SHARING`

The error message: INVALID_FIELD_SHARING: Non-shareable field "Guest.name" is resolved from multiple subgraphs: it is resolved from subgraphs "accounts" and "monolith" and defined as non-shareable in all of them

How to fix it:

If a field in a type (that is not a value type) is defined in both the monolith and the accounts subgraph schemas, then we'll have duplicate definitions of these fields. This will result in a failed composition.
We don't want to share these fields between subgraphs, so ensure that the fields are only defined once, in the appropriate subgraph where they belong.
Review the fields in both the Host and Guest types in both the monolith and accounts subgraphs. Which fields belong in which subgraph?
Refer to the final state of the code shown in the previous section to check your work.

Failed authentication

Rover might indicate that publishing failed due to malformed or invalid credentials.

The error message: error[E014]: The API key you provided is malformed. An API key must have three parts separated by a colon.

How to fix it:

Double-check that the key used to configure Rover matches the APOLLO_KEY provided for your graph. If necessary, generate a new key for your graph by visiting the Settings tab in Apollo Studio, then rerun rover config auth.
You can also check the identity of your configured API key by running the command rover config whoami. An invalid API key produces the error below: error[E013]: The registry did not recognize the provided API key. Check your API key to make sure it's valid (are you using the right profile?).

For more information about configuring Rover to work with graph keys, see the docs on configuring Rover.

Invalid path

Rover might indicate that it can't find a schema file at the specified location.

The error message: error: Invalid path. No file found at ./subgraphs/locations/locations.graphql

How to fix it: Make sure to run the rover subgraph publish command from the root directory of your project. The path to the subgraph schema file should be relative from that directory.

Syntax error

Rover might indicate an error parsing the schema if one of the subgraph files contains invalid syntax.

The error message: error: Could not parse partial schema as AST.

How to fix it: Check the schema and server files for errors, or revisit Lessons 2 and 3 to validate your code.

Incorrectly published subgraph

If one of your subgraphs has been published incorrectly, you might see an error indicating that the request to query your supergraph failed.

The error message: HTTP fetch failed from 'accounts': HTTP fetch failed from 'accounts': error trying to connect: received corrupt message

How to fix it: Publish the impacted subgraph again, checking the accuracy all of the arguments you pass into the rover subgraph publish command. To be sure that you've previously specified the correct routing-url for your subgraph, you can check the SDL tab on the Schema page in Studio. Because our subgraphs are running on localhost, we need to specify http and not https!

Seeing another error?

For any other scenarios not covered here, please see the official docs on Rover errors.

Still having trouble? Visit the Odyssey forums to get help.

With that, we should see that the composition process was successful! Studio is now up to speed on how we've decided to divide fields between our subgraph schemas.

The 'monolith' subgraph for the <APOLLO_GRAPH_REF> graph was updated
The gateway for the <APOLLO_GRAPH_REF> graph was updated with a new schema, composed from the updated 'monolith' subgraph

Testing our schema changes

Let's check the results in our graph on Apollo Studio. Navigate to the Schema page and the SDL tab. We'll see a new subgraph on this list called accounts! 🎉

Next up, we'll put these changes to the test. Head over to the Explorer and run this query:

query GetMyProfile {
  me {
    id
    name
    profilePicture
  }
}

Make sure your Headers are set to:

Authorization: Bearer user-1

When you run the query... uh-oh! We get a new error: Cannot return null for non-nullable field Host.name.

That's because we have yet to move the corresponding resolvers over to the accounts subgraph! (And we'll need to move that me entry point over as well.) Let's take care of the resolvers first, in the next lesson.

Practice

In which of the following scenarios should the @shareable directive be used?

When more than one subgraph should be able to resolve a particular object field (or set of object fields).Whenever any new field is added to a subgraph schema.When an interface is used in more than one subgraph schema.

Key takeaways

The INVALID_FIELD_SHARING error occurs when multiple subgraphs implement the same object type field without designating it as shareable.
Applying the @shareable directive enables multiple subgraphs to resolve a particular object field (or set of object fields). This allows the field(s) to which the directive is applied to exist in more than one subgraph.

Up next

We don't have any resolvers set up in the accounts subgraph, so we aren't getting any data back about users! Let's tackle that next.

Share your questions and comments about this lesson

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.