Overview

We've got our project ready and a local supergraph is running. Let's get to know our REST API and take the first steps to using Apollo Connectors.

In this lesson, we will:

• Examine the Listings REST API
• Use the @source directive to define a REST API data source in the schema

Airlock's Listings REST API

Let's take a brief look at the REST API we want to pull into our graph.

Open up the Listings REST API: https://rt-airlock-services-listing.herokuapp.com/

The default response from our REST API is pretty barebones: just a "Hello World!" message and no documentation about what it can do. That's what we're working with! We'll explore the different resource endpoints and responses later on.

For now, let's define this API in our schema in a way that helps us refer to it easily.

The @source directive

The @source directive defines a shared data source for multiple connectors.

It takes in two parameters: name and http.

• name: A unique identifier for the data source.
• http: An object that defines the baseURL string and an array of headers for the data source.

For us, this means that we'll use @source to define the Listings REST API as a data source that can populate fields in our schema. Let's do it!

Importing the @source directive

First, we'll need to import the directive into the schema.

1. Open up the listings.graphql schema file.

2. At the top of our file is the schema definition—it lets us extend our schema with extra capabilities, such as federation support. We'll append a new @link, with a url to the connectors spec, and an import array that contains the "@source" directive.

   listings.graphql

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

   Copy

Applying the @source directive

We're ready to put @source to use!

1. Below the @link where we imported the directive, we'll add a new line that applies @source.

   If you're using the VS Code extension, you should see a prompt to auto-complete the variables we need for @source by hitting Enter. Pretty handy!

   listings.graphql

   extend schema
     @link(url: "https://specs.apollo.dev/federation/v2.10", import: ["@key"])
     @link(
       url: "https://specs.apollo.dev/connect/v0.1"
       import: ["@source"]
     )
     @source(name: "", http: { baseURL: "" })

   Copy

2. Let's fill in those parameters. Our new data source requires a name, which we'll use to uniquely identify it. We'll name it v1.

   listings.graphql

   @source(
     name: "v1"
   )

   Copy

   Note that you can choose to name the source anything you want, as long as you're referring to it properly inside the connector (which we'll see in the next lesson!).

3. Finally, we need to set the baseURL of the API to "https://rt-airlock-services-listing.herokuapp.com/". This gives us the foundational URL where all of our requests will be directed (we'll see how to apply specific endpoints later on).

   listings.graphql

   @source(
     name: "v1"
     http: { baseURL: "https://rt-airlock-services-listing.herokuapp.com/" }
   )

   Copy

Uh-oh! Build errors in rover dev

If we save our changes, rover dev will automatically restart composition with the latest schema and we'll unfortunately see errors in the console! What's going on?

This is actually expected! By adding the @link to the connectors spec, we've made our schema connectors-enabled, and Rover is treating it as such.

The errors are telling us that fields in our schema have no way of being resolved right now. They're also giving us a helpful hint on how to solve it: using the @connect directive.

Practice

Key takeaways

• The @source directive defines a shared data source for multiple connectors.
• The @source directive takes in two parameters: name and http.

Up next

We've got those build errors to fix in the next lesson!