Adding a mutation to our schema

3. Adding a mutation to our schema

Overview

We know how mutations should look in a schema. Next we'll add incrementTrackViews and a dedicated response type to Catstronauts.

In this lesson, we will:

Add a Mutation type to our schema
Define incrementTrackViews with a required id argument
Create an IncrementTrackViewsResponse type with status fields and a nullable track

✍️ Updating our schema

To add a mutation, let's go to our schema in our server/src folder, in the schema.graphql file.

We'll start with the type keyword, then Mutation, followed by curly braces.

type Mutation {

}

We want to increment the number of views for a track, so we'll call this mutation incrementTrackViews. This mutation needs to know which track to update, so we'll open up parentheses, and inside, we add an argument called id. This argument's type is ID, and it's required, so we'll add an exclamation point (!) at the end.

incrementTrackViews(id: ID!)

We need a return type for this mutation. We could return a single Track because that's what this mutation updates, but as we saw in the previous lesson, there's a better approach.

Let's create a new type for our mutation response. Following convention, we'll combine the name of our mutation (IncrementTrackViews) with Response.

type IncrementTrackViewsResponse {

}

This type will have the three fields we mentioned earlier:

code (a non-nullable Int)
success (a non-nullable Boolean)
and message (a non-nullable String)

Finally, we'll add the objects that were modified. In our case, we only had one: track of type Track. Note that track can be null, because our mutation might fail.

Let's also add comments for each of these fields so that it makes our GraphQL API documentation more useful.

"Similar to an HTTP status code, represents the status of the mutation"
code: Int!
"Whether the mutation completed successfully"
success: Boolean!
"A human-readable message for display in the UI"
message: String!
"The updated track after a successful mutation; null if the mutation failed"
track: Track

Lastly, we can set the return type of our mutation to this new IncrementTrackViewsResponse type, and make it non-nullable. Here's what the incrementTrackViews mutation should look like now:

server/src/schema.graphql

type Mutation {
  "Increment the number of views for a track when its card is clicked"
  incrementTrackViews(id: ID!): IncrementTrackViewsResponse!
}

Code review

type Query {
  "Fetch a list of tracks for the homepage grid"
  tracksForHome: [Track!]!
  "Fetch a specific track by ID"
  track(id: ID!): Track!
  "Fetch a specific module by ID"
  module(id: ID!): Module!
}

"Educational modules teaching a specific topic"
type Track {
  "The unique identifier for the track"
  id: ID!
  "The title of the track"
  title: String!
  "The track's primary author"
  author: Author!
  "The URL of the track's illustration, used in the track card and track detail page"
  thumbnail: String
  "The track's approximate length to complete, in minutes"
  length: Int
  "The number of modules contained in this track"
  modulesCount: Int
  "The track's full description, which may include Markdown"
  description: String
  "The number of times this track has been viewed"
  numberOfViews: Int
  "The ordered list of modules that make up this track"
  modules: [Module!]!
}

"An author of a track or module"
type Author {
  "The unique identifier for the author"
  id: ID!
  "The author's first and last name"
  name: String!
  "The URL of the author's profile picture"
  photo: String
}

"A single unit of teaching. Multiple modules compose a track"
type Module {
  "The unique identifier for the module"
  id: ID!
  "The title of the module"
  title: String!
  "The module's length, in minutes"
  length: Int
  "The module's text content, which may include Markdown; for video modules, this is the enriched transcript"
  content: String
  "The URL of the module's video, when the module is video-based"
  videoUrl: String
}

type Mutation {
  "Increment the number of views for a track when its card is clicked"
  incrementTrackViews(id: ID!): IncrementTrackViewsResponse!
}

"Response payload returned after attempting to increment a track's view count"
type IncrementTrackViewsResponse {
  "Similar to an HTTP status code, represents the status of the mutation"
  code: Int!
  "Whether the mutation completed successfully"
  success: Boolean!
  "A human-readable message for display in the UI"
  message: String!
  "The updated track after a successful mutation; null if the mutation failed"
  track: Track
}

Practice

In the mutation response type (IncrementTrackViewsResponse), why is the modified object's return type nullable (track: Track)?

It should actually be non-nullable and we made a mistakeThe mutation might encounter errors that prevent a Track from being modifiedEvery response type is required to have at least one nullable fieldOnly scalar schema fields can be nullable

Code Challenge!

Update Mutation.createPlanet to accept an input of type non-null CreatePlanetInput and return a non-null CreatePlanetResponse type. Next, complete CreatePlanetInput with name and mass fields. (See the Planet type for reference!)

Loading progress

Up next

Now that our schema is good to go, let's figure out what endpoints we'll need to use to update our data.

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.