Overview

Let's prepare our dev environment and get to know the project we're building.

We'll need a few things to get started. In this lesson, we will:

• Verify our Apollo GraphOS account
• Set up our local code environment
• Run rover dev with graph credentials

1) Verify your Apollo GraphOS account

To use connectors, you'll need an Apollo GraphOS account.

Don't have an account yet? Create one now and you're all set! Jump to the next step.

If you already have an existing account within an organization with an Enterprise plan, you must have the role of Graph Admin to be able to create graphs and retrieve graph credentials in Step 3.

2) Set up your local code environment

Next up, let's clone our starter project, and open it up in our code editor.

Your project directory will look something like this:

2b) Install the Apollo VS Code Extension

We recommend using VS Code for this project so we can use the Apollo VS Code extension. It brings many helpful features for working on a GraphQL project, such as autocompletion, schema information, syntax highlighting and much more!

Install the Apollo VS Code extension.

Alternatively, if you use an IntelliJ-based IDE, you can install our JetBrains plugin. Check out the documentation for IDE Support for more information.

We've already got a few files to start off with: config files as well as a minimal GraphQL schema in the listings.graphql file. We'll build onto this throughout the course.

3) Run rover dev with graph credentials

The Rover CLI includes a command called rover dev that will spin up our API, specifically a router we can work with locally. We'll learn more about what the router does later on. But to enable connectors, Rover first needs a graph's credentials.

1. Let's head over to GraphOS Studio in the browser.

2. If you have a brand new organization, you'll see the following screen encouraging you to get started with the Rover CLI.

   studio.apollographql.com

   

   If you already have existing graphs, click Add new graph, then select Connect a REST API.

   studio.apollographql.com

   

   For users with existing graphs: Please note that the remainder of your graph setup steps might differ slightly from what we've detailed here. You should still refer to the steps below to install the Rover CLI, provide your graph details, and authenticate Rover with an API key.

3. Find the command in the installation instructions that fits with your environment.

   For Linux / Mac OS:

   curl -sSL https://rover.apollo.dev/nix/latest | sh

   Copy

   For Windows PowerShell installer

   iwr 'https://rover.apollo.dev/win/latest' | iex

   Copy

   Note: You can find other installation methods in the Apollo documentation.

4. If you've already installed Rover before, you'll get a message asking if you'd like to overwrite the existing installation. Type y and hit enter to continue.

5. Verify that the installation completed successfully:

   rover --version

   Copy

   To work with connectors, your Rover version should be at least on v0.28.0.

6. Next, let's make sure we're authenticated to Rover. Copy the rover config auth command, and run it in your terminal.

   rover config auth

   Copy
   studio.apollographql.com

   

7. Rover will ask you for a personal API key to finish authenticating. Back in Studio, click the Generate API key button. This opens a dialog where you can provide a name for this new key. Click Create, then copy the generated key that appears on the next screen.

8. Back in the terminal, paste the key and press enter to provide it to the Rover CLI.

   Task!

   I've installed the Rover CLI.

9. In Studio, we'll jump down to the third step on the page. We're working with a REST API, so we'll click the Connect a REST API button.

   studio.apollographql.com

   

10. This opens up a modal asking for some details about our graph. We'll give it a name, keep the defaults, then hit Create and continue.

    studio.apollographql.com

    

11. This next page outlines how to set up our local development environment using an example subgraph. It's great for getting started quickly, but we've already got our starter code, so we won't need to do all the steps in this process!

    studio.apollographql.com

    

12. On to the next step! We're already starting with a supergraph.yaml file in our project repo, and a schema, so that's the next two steps done.

13. Scrolling down to the next step, we've got the graph credentials. Let's copy and paste over the values for APOLLO_KEY and APOLLO_GRAPH_REF into our rover-dev.md file in the code editor, choosing the one that fits your local environment.

    studio.apollographql.com

    

    Make sure you hit the icon to reveal masked values so that the unmasked value for APOLLO_KEY is copied over.

    studio.apollographql.com

    

    rover-dev.md

    #  sh
    APOLLO_KEY="..." \
    APOLLO_GRAPH_REF="..." \
    rover dev --supergraph-config supergraph.yaml --router-config router-config.yaml
    
    # Powershell
    $env:APOLLO_KEY="..."
    $env:APOLLO_GRAPH_REF="..."
    rover dev --supergraph-config supergraph.yaml --router-config router-config.yaml

    Copy

    This rover dev command takes in our graph credentials and two configuration files (supergraph.yaml and router-config.yaml). You can take a look at them if you're curious.

14. Copy the command and run it in the terminal. We'll see a few lines of output and a message that the router has started up at port 4000.

15. We can head over to http://localhost:4000 in the browser, where we've got another handy tool ready for us: Apollo Sandbox, a local playground that lets us explore our GraphQL API.

    With its Explorer, we can build operations easily, send requests and debug our connector calls.

What we're building

That's our setup, but what exactly are we building? Let's meet our course project: Airlock.

Airlock is an intergalactic travel booking app, where we can find a cool place to stay in the wide open universe! You can find the demo project here: https://odyssey-airlock.netlify.app/

We'll be building the API for Airlock and we've got big plans, but right now, we'll start small.

We have a simple REST API with a few endpoints that let us explore the listings for our travels, giving us detailed information about places we could stay at, their amenities, how many beds and the cost.

You can find the REST API here: https://airlock-listings.demo-api.apollo.dev/

We'll use a few pages of Airlock mockups to guide us; we'll determine what pieces of data from which endpoints of the REST API we'd need to orchestrate.

Key takeaways

• To get started with Apollo Connectors, you need an Apollo account.
• To start up a local router for our API, we'll need to provide Rover with our graph credentials.

Up next

We're all set up, so let's dive into how we use connectors in the schema.