Overview

Let's get things going in the schema, starting with the @source directive. Remember, this is where we define the core information about the data source, like its URL and any headers. We'll refer to this @source with the @connect directive in the next lesson.

In this lesson, we will:

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

The schema

Let's open up the listings.graphql file.

Here we have a very minimal schema to kick off our course project, Airlock.

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 have one entry point to start: Query.featuredListings, which returns a list of Listing types. A Listing has an id and title for now; we'll add more later on.

Now where exactly will this data be coming from? We'll be using an existing REST API as our data source: https://airlock-listings.demo-api.apollo.dev/

Let's get this source set up in our schema.

Importing the @source directive

First, we'll need to import the directive.

1. At the top of the listings.graphql file is the schema definition—it lets us extend our schema with extra capabilities, like the GraphQL Federation support already included.

2. We'll append a new @link, with a url to the Connectors spec, and an import array that contains "@source".

   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

Now we're ready to use it!

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

2. If you're using a supported editor, you should see a prompt to auto-complete the required parameters 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

3. Let's fill these in. Our data source requires a name, which we'll use to uniquely identify it. You can choose to name the source anything you want. We'll name it listings.

   listings.graphql

   @source(
     name: "listings",
     http: { baseURL: "" }
   )

   Copy

4. Finally, we need to set the baseURL to point to our REST API: https://airlock-listings.demo-api.apollo.dev. This gives us the foundational URL where all of our requests will be directed. We'll see how to apply specific paths and endpoints later on.

   listings.graphql

   @source(
     name: "listings"
     http: { baseURL: "https://airlock-listings.demo-api.apollo.dev" }
   )

   Copy

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: "listings"
    http: { baseURL: "https://airlock-listings.demo-api.apollo.dev" }
  )

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!
}

Uh-oh! Build errors in rover dev

When we save our file, Rover detects the changes and checks to see if the new schema is valid. In this case, we've got errors!

error[E029]: Encountered 1 build error while trying to build a supergraph.

Caused by:
    QUERY_FIELD_MISSING_CONNECT: [listings] The field `Query.featuredListings`
      has no `@connect` directive.

By adding the link to the Connectors spec, we've essentially told Rover to expect a schema with Connectors. In this case, we haven't added any yet! Fortunately, we see a helpful hint on how to move forward: using the @connect directive.