Overview

The Query.featuredListings field needs to know what data it should return!

In this lesson, we will:

• Learn about the @connect directive syntax
• Use @connect to retrieve data for a Query field

Featured listings

Let's take a step back from our schema and examine the project we're building. Airlock's homepage needs to display an array of featured listings along with a few properties. In this lesson, we'll start small and tackle the id and title fields first.

This data will be powered by the GET /featured-listings endpoint from our Listings REST API. We can examine the response from that endpoint here: https://rt-airlock-services-listing.herokuapp.com/featured-listings

Now how do we take this data and connect it to our GraphQL schema?

The @connect directive

The @connect directive describes how to get the data for a GraphQL field from a REST endpoint. We refer to each instance of @connect as a connector.

Every field on the Query and Mutation types must have a @connect directive. (As we saw in our build errors, we need to provide one for featuredListings!)

@connect takes in four parameters:

• source: A unique identifier for the data source, mapping back to the name value defined in an @source instance.
• http: An object that defines the HTTP methods and URL parameters for the data source.
• selection: Maps an API's JSON response to GraphQL fields
• entity: If set to true, the field acts as an entity resolver in Apollo Federation. We won't be using this in the course.

Importing the @connect directive

To start, we'll need to let our schema know about the directive.

1. At the top of the listings.graphql schema, find the line where we imported the @source directive from the connectors spec.

   listings.graphql

   @link(
     url: "https://specs.apollo.dev/connect/v0.1"
     import: ["@source"]
   )

2. Add the @connect directive to the array of imports.

   listings.graphql

   import: ["@source", "@connect"]

   Copy

@connect and featured listings

1. Find the Query.featuredListings field in the schema.

   listings.graphql

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

2. Append the @connect directive to the field.

   Again, let's take advantage of the auto-complete the Apollo VS Code extension gives us. Hit Enter and get all the @connect parameters ready to be filled in!

   listings.graphql

   featuredListings: [Listing!]!
     @connect(
        source: ""
        http: { GET: "" }
        selection: """
   
        """
      )

   Copy

3. First, the source parameter. Let's set the value to v1 as we defined in the previous lesson when using @source.

   listings.graphql

   source: "v1"

   Copy

4. Next, the http.GET parameter should send a request to the /featured-listings endpoint, as we saw earlier.

   listings.graphql

   http: { GET: "/featured-listings" }

   Copy

Finally, we just have selection left!

The selection mapping

The selection property contains a mapping for the fields defined in our schema to the data properties returned from the JSON response of the endpoint.

In our case, our schema needs the Listing.id and Listing.title fields to be mapped to the JSON response.

1. Open up the REST API endpoint for /featured-listings: https://rt-airlock-services-listing.herokuapp.com/featured-listings

2. In the JSON response, we can see the properties for id and title are returned for each item in the array. These are exactly the properties we need! Let's add them to the selection.

   listings.graphql

   selection: """
   id
   title
   """

   Copy

The Query.featuredListings field should now look like this:

Let's recap what this code is doing.

• To resolve our Query.featuredListings field, we've set up our schema with our REST API source, named "v1". We've used the @connect directive to "connect" this field to that source.
• Next, we've used the http property to describe the operation and endpoint that retrieves the data needed for this field. In this case, that's GET: "/featured-listings". (Because we already defined baseUrl in our initial source definition, we can just reference the specific endpoint we want to use here.)
• Finally, we've defined the selection of properties we want to pluck from each item in the response: namely, id and title.

Checking our work

Ready to see the magic? Let's save our changes and jump over to http://localhost:4000 where our local router is running.

Let's build an operation asking for our featuredListings, their id and title. You can build this yourself using the Explorer's Documentation panel and clicking the + buttons, or by copying and pasting the operation below:

Run the operation and... you should get data back! 🎉

With just a few lines added to our schema, we've used Apollo Connectors to plug into an existing REST API—and we didn't write a single line of resolver code! 👏

Practice

Key takeaways

• The @connect directive describes how to get the data for a particular GraphQL field using a defined source.
• We pass the http parameter to define the HTTP methods and URL parameters on the source that should be used to retrieve data for a field.
• We can map the REST API's JSON response to our GraphQL fields by passing the selection parameter, which lets us define the specific properties on the response that we want.
• The fourth parameter we can pass to @connect, entity, enables the field to act as an entity resolver in Apollo Federation.

Up next

We started small with id and title, but there's more to show for a listing! Let's add more fields and see what happens when our mapping doesn't quite match one-to-one.