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

Don't have an account yet? Create one now and you're all set with the Free plan! 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.

The Rover CLI is the primary command-line interface for managing and maintaining graphs with Apollo. We'll be using it to get a local project set up and running.

1. Find the command that fits with your environment to install the latest version of Rover.

   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.

2. 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.

3. Verify that the installation completed successfully:

   rover --version

   Copy

   To complete this course, your Rover version should be at least on v0.30.0.

4. Next, let's make sure we're authenticated to Rover. Run the rover config auth command in your terminal.

   rover config auth

   Copy

5. Rover will ask you for a personal API key to finish authenticating. Let's head over to GraphOS Studio in the browser to retrieve that key.

6. If you have a brand new organization, you'll see instructions for installing and authenticating Rover. On the second step, click Generate API key. We'll give this key any name (for example, dev), click Create, then copy the key.

   studio.apollographql.com

   

   For users with existing graphs: Click on your avatar on the top right and select Personal Settings. Under the API Keys tab, hit Create new key, give this key any name (for example, dev), click Create, then copy the key.

   studio.apollographql.com

   

7. Back in the terminal, paste the key and press Enter to authenticate Rover.

We're ready to start a local project using rover init. The init command starts up a wizard that creates a project template.

1. In a terminal window, create an empty directory for the project.

2. Then, run the command:

   rover init

   Copy

3. Walking through the wizard questions, select the answers below to create a project with Connectors.

   Prompt	Selection
   Select option	Create a new graph
   Select organization	Select the GraphOS organization you want to create your graph in
   Select use case	Start a graph with one or more REST APIs
   Name your graph	Enter a name for your graph, for example, Odyssey Airlock
   Confirm or modify your graph ID	A graph ID is generated based on your graph name. It may contain additional characters to make it unique. Confirm or modify it.

4. Lastly, hit Y to let Rover create the project for us. After a few moments, we'll see an outline of the files created, our graph credentials, and the command we need to spin up the project.

5. Copy the command in the terminal that matches your local environment and run it. Note that you'll have your own graph credentials substituted in:

APOLLO_KEY=<YOUR_APOLLO_KEY> \
APOLLO_GRAPH_REF=<YOUR_APOLLO_GRAPH_REF> \
rover dev --supergraph-config supergraph.yaml

$env:APOLLO_KEY="<YOUR_APOLLO_KEY>"; `
$env:APOLLO_GRAPH_REF="<YOUR_APOLLO_GRAPH_REF>"; `
rover dev --supergraph-config supergraph.yaml

We'll see a few lines of output and a message that the router has started up at port 4000.

Optional: Run a query

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.

In the Explorer, paste the following GraphQL query in the Operation section:

query GetProducts {
   products {
      id
      name
      description
   }
}

Click ► GetProducts to run the request. You'll get a response back with data for the product's id, name, and description; exactly the properties we asked for in our query! 🎉

The rover init wizard set up a working GraphQL service for you, with an example schema and all the files you need to get started!

When working on a GraphQL project, it's helpful to have features such as autocompletion, schema information, and syntax highlighting.

• For VS Code: install the Apollo VS Code extension.
• For an IntelliJ-based IDE: install the Apollo JetBrains plugin.

Check out the documentation for IDE Support for more information.

To enable the extension to work with Connectors, create a new file called apollo.config.yaml and paste the snippet below:

# Configuration for Apollo's VSCode extension
rover: {}

Note: You can still follow along with the course with any code editor, you just won't see tips and in-development errors while you code.

Right now, we have a products schema, but we need listings! Let's go ahead and add that schema.

1. Open up the project in the code editor.

2. First, we'll create a new file called listings.graphql to represent our domain with Airlock.

   📂 odyssey-connectors-intro-rest
     ┣ ...other files
   + ┣ 📄 listings.graphql
     ┣ 📄 products.graphql
     ┗ 📄 supergraph.yaml

3. Then, add the following starter schema to the file:

extend schema
   @link(url: "https://specs.apollo.dev/federation/v2.10", import: ["@key"])

type Query {
   "A curated array of listings to feature on the homepage"
   featuredListings: [Listing!]!
}

"A particular intergalactic location available for booking"
type Listing {
   id: ID!
   "The listing's title"
   title: String!
}

We're starting with one entry point to our schema (Query.featuredListings) and one object type (Listing). No Connectors yet, we'll get to that!

4. We'll also need to update our supergraph.yaml configuration file. This is how Rover knows where our schemas live. We'll replace all references to products with listings.

subgraphs:
   listings:
      routing_url: http://ignore
      schema:
         file: listings.graphql
federation_version: =2.10.0