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

Don't have an account yet? Create one now and get started 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 use it to set up and run a local project.

1. Find the command that fits 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 0.33.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 launches a wizard to create a project template.

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

2. Run the command:

   rover init

   Copy

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

   Prompt	Selection
   Select option	Create a new graph
   Select organization	Select the GraphOS organization to create the graph in
   Select use case	Start a graph with one or more REST APIs
   Name your graph	Enter a name for the graph, e.g., Odyssey Airlock
   Confirm or modify your graph ID	Confirm or modify the generated graph ID.

4. Lastly, hit Y to let Rover create the project. After a few moments, we'll see an outline of the created files, graph credentials, and the command 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 output confirming the router has started on port 4000.

Optional: Run a query

Head to http://localhost:4000 in the browser to use Apollo Sandbox, a local playground for exploring our GraphQL API.

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

query GetProducts {
   products {
      id
      name
      description
   }
}

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

The rover init wizard sets up a working GraphQL service with an example schema and all the files we 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: set up the Apollo VS Code extension.
• For an IntelliJ-based IDE: set up the Apollo JetBrains plugin.

Check out the documentation for IDE Support for more information.

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 the project in the code editor.

2. 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. Add the following starter schema to the file:

extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.11", import: ["@key"])
  @link(
    url: "https://specs.apollo.dev/connect/v0.2"
    import: ["@source", "@connect"]
  )
  @source(
    name: "listings"
    http: { baseURL: "https://airlock-listings.demo-api.apollo.dev" }
  )

type Query {
  "A curated array of listings to feature on the homepage"
  featuredListings: [Listing!]!
    @connect(
      source: "listings"
      http: { GET: "/featured-listings" }
      selection: """
      id
      title
      numOfBeds
      costPerNight
      """
    )
}

"A particular intergalactic location available for booking"
type Listing
  @connect(
    source: "listings"
    http: { GET: "/listings/{$this.id}" }
    selection: """
    id
    title
    numOfBeds
    costPerNight
    description
    photoThumbnail
    latitude
    longitude
    """
  )
  @key(fields: "id") {
    id: ID!
    "The listing's title"
    title: String!
    "The number of beds available"
    numOfBeds: Int
    "The cost per night"
    costPerNight: Float
    "The listing's description"
    description: String
    "The thumbnail image for the listing"
    photoThumbnail: String
    "Latitude coordinates for the destination"
    latitude: Float
    "Longitude coordinates for the destination"
    longitude: Float
}

We're starting with one entry point to our schema (Query.featuredListings) and one object type (Listing).

4. Update the supergraph.yaml configuration file. This tells Rover where our schemas live. Replace all references to products with listings.

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

5. Lastly, we can delete the products.graphql file since we don't need it anymore.

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