Overview
Excited to start connecting soundtrack data directly to recipes? (Finding music for the meal, so to speak!) First, let's make sure we're set up for local development.
In this lesson, we will:
- Review the supergraph development kit GraphOS provides
- Use
rover dev
to do local development with our supergraph
From development to production
Though our router and soundtracks
subgraph are both running locally (with recipes
running at a remote location), we're emulating the same exchange that would occur when we host everything in a live, traffic-ready environment.
As with developing any application, we need a workflow that allows us to make changes locally, test them out, and feel confident that we've taken care of any problems before pushing our changes to production. (Or at least, our version of production, in tutorial-land!)
But short of rolling new changes directly into our running, production supergraph, how do we actually test that our API will keep functioning?
The GraphOS supergraph development kit
Apollo GraphOS provides a supergraph development kit that helps developers build and play with subgraphs within a supergraph architecture quickly and easily.
Andโas you might have guessedโwe've already been using parts of the GraphOS supergraph development kit!
Sandbox is one such tool, a special mode of GraphOS Studio that provides us with Explorer (the GraphQL IDE we've been using to build and run queries against our locally-running subgraph), a schema reference, schema checks, and diffs.
Though we didn't create it ourselves, the recipes
subgraph was bootstrapped using rover template
, providing a starting point for a GraphQL subgraph server with JavaScript. The soundtracks
server that we finished up in the last course with DGS and Java actually is federation-compatible from the start! No changes necessary.
Note: Curious about other templates for different languages bootstrapping a new subgraph? Check out rover template
in the Apollo documentation.
The last piece of our supergraph development kit is rover dev
.
rover dev
for local development
So far, we've seen data from both subgraphs come together by running a local router. Let's envision now that our routerโand both subgraphsโare running somewhere live within our cloud infrastructure.
The time has come to make some changes. We want to make some tweaks in our local copy of soundtracks
, and have real-time validation as we code that our supergraph can still compose when those changes are merged.
A special command in the Rover CLI takes care of this scenario exactly. Let's see how rover dev
fits into our graph development workflow.
Using rover dev
rover dev
lets us start a local routerโright on your computer!โthat can query across one or more subgraphs. Each subgraph can be run locally or remotely. It's a supergraph in our local development environment! This lets us implement and test changes before we publish them to GraphOS.
Now you might be thinking: didn't we already run a router locally? In Lesson 4: Running the router, we downloaded a router and ran it locally.
The key difference? That router was connected to our supergraph schema registry on GraphOS, whereas the router we're about to run with rover dev
will connect to our local subgraph changesโeven when those changes haven't been published to the registry! This lets us play around with new features and schema updates; we can enjoy the safety of our development environment, while simulating how our changes will work when composed with the router and other subgraphs.
To get started, we'll need the soundtracks
subgraph running. If you haven't already, start the soundtracks
subgraph server locally by pressing the play button (if using IntelliJ) or by running the following command:
./gradlew bootRun
The config file
The easiest way to start a rover dev
session with multiple subgraphs is to use a YAML file listing the details for each subgraph.
Create a new file within the router
directory called supergraph-config.yaml
and paste the contents below:
federation_version: =2.7.0subgraphs:soundtracks:routing_url: http://localhost:8080/graphqlschema:file: ./src/main/resources/schema/schema.graphqls # Schema provided via filerecipes: # Schema downloaded from GraphOS registryschema:graphref: # PROVIDE YOUR GRAPH REF HERE!subgraph: recipes
The first line defines the version of Federation we're using.
The properties under subgraphs
are all the names of subgraphs in the supergraph. Let's look at each one.
soundtracks
is running locally, and we're passing the relative path from the root of the soundtracks
directory to the schema.graphqls
file.
Next up is recipes
. This one is pointing to the recipes
subgraph stored in GraphOS. If we were making changes to the recipes
subgraph as well, we'd probably point to a locally-running server and schema, similar to how we've set up soundtracks
.
Important to note is the graphref
property beneath recipes
and schema
. Make sure that you provide your APOLLO_GRAPH_REF
value that we stored in the router/.env
file.
We're ready to start up rover dev
!
Running rover dev
Open up a new terminal in the root of the soundtracks
directory. Let's run rover dev
and pass in the config file with the --supergraph-config
flag.
rover dev --supergraph-config ../router/supergraph-config.yaml
Note: Because the supergraph-config.yaml
file is located in our router
directory, we'll pass the path relative to the soundtracks
directory: namely, moving up a level and then into router
.
After running it, we'll get the following output:
โ ๏ธ Do not run this command in production! โ ๏ธ It is intended for local development.๐ polling http://localhost:5059/graphql every 1 second๐ซ starting a session with the 'recipes' subgraph๐ซ starting a session with the 'soundtracks' subgraph๐ถ composing supergraph with Federation v2.7.1๐ your supergraph is running! head to http://localhost:4000 to query your supergraph๐ถ composing supergraph with Federation v2.7.1โ successfully composed after adding the 'soundtracks' subgraph
Awesome, looks like our supergraph is running at http://localhost:4000. Let's check it out!
Note: By default, rover dev
runs the supergraph on port 4000
. If you would prefer running it on a different port, you can add the additional flag --supergraph-port
(or -p
) and set it to a different value. Just make sure you're not using port 8080
because that's where the soundtracks
subgraph is running!
In the browser, navigate to http://localhost:4000. We'll see Sandbox connected to port 4000
, ready for us to query the local router spawned from rover dev
.
In the Documentation panel, we can see familiar-looking fields from our soundtracks
subgraph. Test out a query for featured playlists and their tracks.
query GetRecipeAndPlaylists($recipeId: ID!) {recipe(id: $recipeId) {cookingTimedescriptioninstructions}featuredPlaylists {name}}
And under the Variables section:
{"recipeId": "recgUKbxnQssl9fYc"}
Run the query and... data! ๐You can confirm the same data was returned in Studio as it is in Sandbox.
We're now free to make any changes we'd like to in the soundtracks
subgraph, and see for ourselves how the router would handle them. We can even spin up a whole new subgraph and add it to our local supergraph.
This is your playground to explore in, to test new concepts, and dream up new featuresโall without impacting the production supergraph!
Practice
rover dev
not do?Key takeaways
- The GraphOS supergraph development kit includes the following: Sandbox,
rover template
androver dev
. rover dev
lets us start a local router that can query across one or more subgraphs.- To use
rover dev
, we need each subgraph's name, the URL where it's running, and (optionally) the path to the schema file. The easiest way to do this is with a supergraph config file.
Up next
We have everything we need to get started on our changes! Let's turn our focus back to that dream query that connects data between a recipe and some recommended playlists to set the mood. For this, we'll need to dive into the supergraph architecture and how the router handles coordination across subgraphs.
Share your questions and comments about this lesson
This course is currently in
You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.