GraphQL mutations with Connectors - GraphQL Tutorials

GraphQL meets REST, with Apollo Connectors

Introducing Apollo Connectors Project setup How Connectors work in the schema Defining a @source The @connect directive Debugging Connectors Arguments Orchestration in action Using entities with Connectors Mutations

10. Mutations

5m

(Text covers the exact same content as the video)

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 use the POST /listings endpoint. Here's what the curl request looks like.

curl request

curl --location 'https://airlock-listings.demo-api.apollo.dev/listings' \
--header 'Content-Type: application/json' \
--header 'Api-Key: ODYSSEY' \
--data '{
  "listing": {
    "title": "GraphQL Summit Home Base",
    "numOfBeds": 4,
    "costPerNight": 404
  }
}'

To send the request, you'll need to provide a value for the Api-Key header. (Here we've included the example ODYSSEY, which you're welcome to use—but any value will work!)

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

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": []
}

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

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

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.

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: """

    """
  )

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"
}
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: []
}
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"
}
]
}

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

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:

Body payload

{
  "listing": {
    "title": "GraphQL Summit Home Base",
    "numOfBeds": 4,
    "costPerNight": 404
  }
}

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

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: """

"""
}
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: {

}
"""
Then we'll start adding those three properties we need.
listings.graphql
body: """
listing: {
title:
numOfBeds:
costPerNight:
}
"""
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
}
"""

There's another, shorter way to write the body mapping:


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

In this alternative, we're using shorthand syntax and unwrapping the $args.input field.

To learn more about the mapping syntax, check out the official documentation.

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.

Rover error

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

Caused by:
    INVALID_SELECTION: [listings] `@connect(selection:)` on `Mutation.createListing` is empty

We need a selection mapping to finish off this Connector!

listings.graphql

createListing(input: CreateListingInput!): CreateListingResponse
    @connect(
    source: "listings"
    http: {
      POST: "/listings"
      headers: [{ name: "Api-Key", from: "Api-Key" }]
      body: """
      listing: {
        title: $args.input.title
        numOfBeds: $args.input.numOfBeds
        costPerNight: $args.input.costPerNight
      }
      """
    }
    selection: """

    """
    )

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: {

}
"""

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": []
}

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

createListing(input: CreateListingInput!): CreateListingResponse
  @connect(
  source: "listings"
  http: {
    POST: "/listings"
    headers: [
      { name: "Api-Key", from: "Api-Key" }
    ]
    body: """
    listing: {
      title: $args.input.title
      numOfBeds: $args.input.numOfBeds
      costPerNight: $args.input.costPerNight
    }
    """
  }
  selection: """
  listing: {
    id
    title
    numOfBeds
    costPerNight
    closedForBooking: closedForBookings
    description
    photoThumbnail
    latitude
    longitude
    amenities {
      id
      name
      category
    }
  }
  """
  )

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.

CreateListing operation

mutation CreateListing($input: CreateListingInput!) {
  createListing(input: $input) {
    listing {
      id
      title
      numOfBeds
      costPerNight
      closedForBooking
      description
      photoThumbnail
      latitude
      longitude
      amenities {
        id
        category
        name
      }
    }
  }
}

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

Variables

{
  "input": {
    "title": "GraphQL Summit Home Base",
    "costPerNight": 404,
    "numOfBeds": 5
  }
}

http://localhost:4000

Adding variables in Sandbox

Adding headers

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

http://localhost:4000

Adding a headers in Sandbox

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.

Response

{
  "data": {
    "createListing": {
      "listing": {
        "id": "d6c46fed-98bc-4ca6-b74f-93f9949c1db3", // you will get a different ID!
        "title": "GraphQL Summit Home Base",
        "numOfBeds": 5,
        "costPerNight": 404,
        "closedForBooking": false,
        "description": "",
        "photoThumbnail": "https://res.cloudinary.com/apollographql/image/upload/v1644353890/odyssey/federation-course2/illustrations/listings-10.png",
        "latitude": null,
        "longitude": null,
        "amenities": []
      }
    }
  }
}

extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.10", import: ["@key"])
  @link(
    url: "https://specs.apollo.dev/connect/v0.1"
    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
      closedForBooking: closedForBookings
      amenities {
        id
      }
      """
    )

  "A specific listing"
  listing(id: ID!): Listing
    @connect(
      source: "listings"
      http: { GET: "/listings/{$args.id}" }
      selection: """
      id
      title
      numOfBeds
      costPerNight
      closedForBooking: closedForBookings
      description
      photoThumbnail
      latitude
      longitude
      amenities {
        id
        category
        name
      }
      """
      entity: true
    )
}

"A particular intergalactic location available for booking"
type Listing @key(fields: "id") {
  id: ID!
  "The listing's title"
  title: String!
  "The number of beds available"
  numOfBeds: Int
  "The cost per night"
  costPerNight: Float
  "Indicates whether listing is closed for bookings (on hiatus)"
  closedForBooking: Boolean
  "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
  "The amenities available for this listing"
  amenities: [Amenity!]!
    @connect(
      source: "listings"
      http: { GET: "/listings/{$this.id}/amenities" }
      selection: """
      id
      name
      category
      """
    )
}

type Amenity {
  id: ID!
  "The amenity category the amenity belongs to"
  category: String!
  "The amenity's name"
  name: String!
}

input CreateListingInput {
  title: String!
  numOfBeds: Int!
  costPerNight: Float!
}

type CreateListingResponse {
  listing: Listing
}

type Mutation {
  createListing(input: CreateListingInput!): CreateListingResponse
    @connect(
      source: "listings"
      http: {
        POST: "/listings"
        headers: [{ name: "Api-Key", from: "Api-Key" }]
        body: """
        listing: {
          title: $args.input.title
          numOfBeds: $args.input.numOfBeds
          costPerNight: $args.input.costPerNight
        }
        """
      }
      selection: """
      listing: {
        id
        title
        numOfBeds
        costPerNight
        closedForBooking: closedForBookings
        description
        photoThumbnail
        latitude
        longitude
        amenities {
          id
          name
          category
        }
      }
      """
    )
}

Task!

I can create a listing 🎉

Lesson tasks

I can create a listing 🎉

Practice

POST requests are usually accompanied by a payload. How do we send that payload to the REST API endpoint using a Connector?

Using the http.body parameterUsing the $body parameterUsing the POST.body parameterUsing the http.payload parameter

Use the following schema to answer the next few questions.

type Mutation {
  createPlanet(input: CreatePlanetInput!): Planet
    @connect(
      source: "outerspace"
      http: {
        POST: "/planets"
        body: """
        ???
        """
      }
      selection: """
      id
      name
      mass
      """
    )
}

type CreatePlanetInput {
  "The planet's name"
  name: String!
  "The total estimated mass of the planet (in kg)"
  mass: Int
}

"Astronomical information for a single planet."
type Planet {
  "The ID for the planet"
  id: ID!
  "The planet's name"
  name: String!
  "The total estimated mass of the planet (in kg)"
  mass: Int
}

Below is an example of a JSON payload for the request body of the POST /planets endpoint.

POST request's body payload

{
  "name": "Mraza",
  "mass": 6.42
}

Which of the following mappings for the body parameter should replace the ??? placeholder in the schema?

name: $args.input.name
mass: $args.input.mass

name: $args.name
mass: $args.mass

name: "Mraza"
mass: 6.42

planet: {
  name: $args.input.name
  mass: $args.input.mass
}

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!

Share your questions and comments about this lesson

Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.

fields

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

fields

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

Apollo Connectors

Apollo Connectors are a declarative programming model for GraphQL, allowing you to plug your existing REST services directly into your graph.

selection mapping

The process of mapping API response data to GraphQL schema fields and types when using Apollo Connectors. Selection mapping occurs within the @connect directive's selection field.

GraphQL

An open-source query language and specification for APIs that enables clients to request specific data, promoting efficiency and flexibility in data retrieval.

mutations

A GraphQL operation that modifies data on the server. It allows clients to perform create, update, or delete operations, altering the underlying data.

fields

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

field

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

fields

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

operations

A single query, mutation, or subscription that clients send to a GraphQL server to request or manipulate data.

argument

A key-value pair associated with a particular schema field that lets operations pass data to that field's resolver.

Argument values can be hardcoded as literal values (shown below for clarity) or provided via GraphQL variables (recommended).

query GetHuman {
  human(id: "200") {
    name
    height(unit: "meters")
  }
}

fields

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

mutation

A GraphQL operation that modifies data on the server. It allows clients to perform create, update, or delete operations, altering the underlying data.

field

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

mutations

A GraphQL operation that modifies data on the server. It allows clients to perform create, update, or delete operations, altering the underlying data.

GraphQL schema

A GraphQL schema defines the structure and types of data that can be queried or mutated, serving as a contract between the server and clients.

field

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

directive

A GraphQL annotation for a schema or operation that customizes request execution. Prefixed with @ and may include arguments. For example, the @lowerCase directive below can define logic to return the username field in lowercase:

type User {
  username: String! @lowerCase
}

field

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

argument

A key-value pair associated with a particular schema field that lets operations pass data to that field's resolver.

Argument values can be hardcoded as literal values (shown below for clarity) or provided via GraphQL variables (recommended).

query GetHuman {
  human(id: "200") {
    name
    height(unit: "meters")
  }
}

field

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

mutation

A GraphQL operation that modifies data on the server. It allows clients to perform create, update, or delete operations, altering the underlying data.

field

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

fields

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

fields

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

mutation

A GraphQL operation that modifies data on the server. It allows clients to perform create, update, or delete operations, altering the underlying data.

fields

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}