Adding a mutation to our schema

3. Adding a mutation to our schema

✍️ Updating our schema

To add a mutation, let's go to our schema in our server/src folder, in the schema.js 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 HTTP status code, represents the status of the mutation"
code: Int!
"Indicates whether the mutation was successful"
success: Boolean!
"Human-readable message for the UI"
message: String!
"Newly updated track after a successful mutation"
track: Track

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

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

type Mutation {
  incrementTrackViews(id: ID!): IncrementTrackViewsResponse!
}

Code Challenge!

Add a mutation to this existing schema. The mutation should assign a spaceship to a specific mission. It should be called assignSpaceship. It takes in two required arguments: a spaceshipId of type ID!, and a missionId of type ID!. It should return a non-nullable type AssignSpaceshipResponse. This return type should return the three informational properties discussed above, as well as nullable spaceship and mission fields with corresponding return types.

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.