Overview

There's more to APIs than just reading data. We need to be able to do things with our data as well, which is where GraphQL mutations come in. Let's tackle one last feature: creating a listing.

In this lesson, we will:

• Set up a connector with a POST request that accepts a body
• Learn about how to craft a selection with nested properties

Create a listing

On the REST API side, we'll be using the POST /listings endpoint. Here's what the curl request looks like.

To send the request, you'll need to provide a value for the Api-Key header.

And here's the shape of the data we receive back:

We'll need to map this response to our schema, and learn how to send a POST request with a body payload using connectors.

Setting up the schema

1. First, let's add the types and fields we need in the schema to make this feature come to life.

   listings.graphql

   input CreateListingInput {
     title: String!
     numOfBeds: Int!
     costPerNight: Float!
   }
   
   type CreateListingResponse {
     listing: Listing
   }
   
   type Mutation {
     createListing(input: CreateListingInput!): CreateListingResponse
   }

   Copy

   We've added a new root field under the Mutation type, where we organize fields that handle write operations. createListing takes in an input argument: CreateListingInput. This type consists of three required fields: title, numOfBeds and costPerNight. Finally, the mutation returns a CreateListingResponse type; this has one field called listing, which returns the Listing type.

   Note: If you need a refresher on mutations and input types in the GraphQL schema, check out graphql.com/learn.

2. If we save our changes now, we'll see that familiar error.

   rover dev error

   error[E029]: Encountered 1 build error while trying to build a supergraph.
   
   Caused by:
       MUTATION_FIELD_MISSING_CONNECT: [listings] The field `Mutation.createListing` has no `@connect` directive.

Adding a connector

Every root field needs a connector, so let's get to it.

1. Let's append the @connect directive to the createListing field, defining the source as usual.

   listings.graphql

   createListing(input: CreateListingInput!): CreateListingResponse
     @connect(
       source: "listings"
       http: { GET: "" }
       selection: """
   
       """
     )

   Copy

2. Next up, for http, we'll need to change the GET call to a POST call and point to the /listings endpoint.

   listings.graphql

   http: {
     POST: "/listings"
   }

   Copy

3. As we saw in the curl command, we need to include a header called Api-Key. We can add that to our http object under the property headers, which contains an array.

   listings.graphql

   http: {
    POST: "/listings",
    headers: []
   }

   Copy

4. For each header object, we can specify the name property, which in this case is Api-Key.

   listings.graphql

   http: {
    POST: "/listings",
    headers: [
      {
        name: "Api-Key"
      }
    ]
   }

   Copy

5. We also need to specify the header value. We could hard-code the value we're using here (under the value property).

   listings.graphql

   http: {
    POST: "/listings",
    headers: [
      {
        name: "Api-Key",
        value: "ODYSSEY" # ⬅️ We could hard-code the value here
      }
    ]
   }

6. Or we can propagate user input. Using the from property, we'll set the value to the name of the header we're propagating from (which will also be called Api-Key!). We'll see how this works in action later on.

   listings.graphql

   http: {
    POST: "/listings",
    headers: [
      {
        name: "Api-Key",
        from: "Api-Key" # ⬅️ Let's propagate it from user input instead!
      }
    ]
   }

This call still needs a body! This will be a mapping similar to selection, but going the other way around: mapping schema to JSON.

Crafting the body mapping

Let's look at the shape of that body payload from our curl request again (the --data value). This is the end result we want:

We've got listing set to an object with three properties: title, numOfBeds and costPerNight.

1. Let's reflect that back in our connector. Still within the http object, we'll add a body parameter and triple quotes.

   listings.graphql

   http: {
     POST: "/listings"
     headers: [{ name: "Api-Key", from: "Api-Key" }]
     body: """
   
     """
   }

   Copy

2. Inside, we'll define the name of the top-level property, which is listing, followed by a colon, with the value set to an object.

   listings.graphql

   body: """
   listing: {
   
   }
   """

   Copy

3. Then we'll start adding those three properties we need.

   listings.graphql

   body: """
   listing: {
     title:
     numOfBeds:
     costPerNight:
   }
   """

   Copy

4. Each of these will need a value, and it should come from the input argument that gets passed in from the client. Remember, we can access arguments with $args. So for the title, we'll need $args.input.title. We'll also follow the same pattern for numOfBeds and costPerNight.

   listings.graphql

   body: """
   listing: {
     title: $args.input.title
     numOfBeds: $args.input.numOfBeds
     costPerNight: $args.input.costPerNight
   }
   """

   Copy

And we're all done with the body of the POST request!

Crafting the selection mapping

If we save our changes now, we'll get an error.

We need a selection mapping to finish off this connector!

1. This mutation needs to return a CreateListingResponse type, which contains a listing field that returns a Listing type. First, we'll define that top-level listing property, followed by a colon, with the value set to an object.

   listings.graphql

   selection: """
   listing: {
   
   }
   """

   Copy

2. Let's pull up that response object again to help us out. It looks like the response has all the properties we need to map to our schema's Listing fields, pretty much one-to-one. (Even if some of them are null or empty!)

   Response from curl request

   {
     "id": "06611dcd-f21f-4676-a02c-ad4b205c6d64",
     "title": "GraphQL Summit Home Base",
     "description": "",
     "costPerNight": 404,
     "numOfBeds": 4,
     "hostId": "user-4",
     "locationType": "CAMPSITE",
     "photoThumbnail": "https://res.cloudinary.com/apollographql/image/upload/v1644353890/odyssey/federation-course2/illustrations/listings-10.png",
     "isFeatured": false,
     "closedForBookings": false,
     "latitude": null,
     "longitude": null,
     "amenities": []
   }

3. Let's add all of those fields. Make sure you rename closedForBookings to closedForBooking to match our schema!

   listings.graphql

   selection: """
   listing: {
      id
      title
      numOfBeds
      costPerNight
      closedForBooking: closedForBookings
      description
      photoThumbnail
      latitude
      longitude
      amenities {
        id
        name
        category
      }
    }
   """

   Copy

Checking our work

Moment of truth! Let's check out Sandbox and start to build out this mutation, adding the fields we need from the sidebar.

We'll need to provide the input in the Variables section with the details of the listing we're creating.

Adding headers

Under the Headers section, let's add a new header, called Api-Key, passing in a value.

Remember, we built our connector to take the value from this header and propagate it to our REST API call.

Go ahead and run it! And we get data back with the details of our new listing, complete with an id generated from the REST API.

Practice

Use the REST API body payload below to complete the code challenge.

Key takeaways

• We can apply connectors to Mutation type fields just as we do for Query type fields.
• When submitting data to a POST endpoint, we can include a body in our connector's http definition.

Conclusion

Well done! You've successfully built an API powered by Apollo Connectors. You now have the tools and patterns to keep on exploring and building.

Let us know about what you're creating, and what you'd like to see next. Drop us a note in the community forum.

Want to keep learning? Dive deeper into the selection mapping syntax with Expressions in connectors: Mapping and Transforms.

See you next time!