Overview

So far, we've only been working with one type of GraphQL operation: queries. These are read-only operations to retrieve data. To modify data, we need to use another type of GraphQL operation: mutations, which are write operations.

In this lesson, we will learn about common conventions for designing mutations and mutation responses

Mutations

On to the next feature in our MusicMatcher project: adding tracks to an existing playlist.

Let's take a look at the corresponding REST API method that enables this feature: POST /playlists/{playlist_id}/tracks.

From the documentation, we need the following parameters:

• playlist_id: The ID of the playlist, as a string (required)
• position: An integer, zero-indexed, where we want to insert the track(s)
• uris: A comma-separated string of uri values corresponding to the tracks we want to add

The method then returns an object with a snapshot_id property that represents the state of the playlist at that point in time.

All right, now how do we enable this functionality in GraphQL?

Designing mutations

Let's start with our schema.

For mutation names, we recommend starting with a verb that describes the specific action of our update operation (such as add, delete, or create), followed by whatever data the mutation acts on.

For the return type of a mutation, we could return the object type the mutation is acting on. However, we recommend following a consistent Response type for mutation responses.

Mutation responses

We'll need to account for any partial errors that might occur and return helpful information to the client. We recommend adding three common fields to all mutation responses:

• code: an int that refers to the status of the response, similar to an HTTP status code.
• success: a bool flag that indicates whether all the updates the mutation was responsible for succeeded.
• message: a string to display information about the result of the mutation on the client side. This is particularly useful if the mutation was only partially successful and a generic error message can't tell the whole story.

Then, we'll also have a field for the object type we're mutating (Playlist, in our case). In certain mutations, this could be multiple objects!

As for naming conventions, return types usually end with the word Payload or Response.

The AddItemsToPlaylistPayload type

Following the best practices we covered, we'll name our mutation AddItemsToPlaylist. Let's first create the return type for this mutation: AddItemsToPlaylistPayload.

Under Types, we'll create a new class file called AddItemsToPlaylistPayload.

Then, we'll add the properties for code, success and message.

The object we're mutating in this case is a Playlist type, which is nullable because it's possible that something can go wrong in the mutation!

Lastly, we'll add the constructor. Remember to make the playlist parameter nullable! It's possible that the mutation could fail and we don't receive a playlist object.

A new entry point: Mutation

Under Types, we'll create a new class file called Mutation.

Next, we'll write the resolver function for our AddItemsToPlaylist field. It will return the AddItemsToPlaylistPayload type. We'll add a description for it too.

Then, we'll hard-code the results of the resolver for now. Small steps! We'll create a new AddItemsToPlaylistPayload instance, passing in 200 for code, true for the success status, a successful message and a hard-coded Playlist object.

Our GraphQL server needs to know about this new entry point to the schema. Much like the Query type, we'll need to call AddMutationType on the GraphQL server and pass in the Mutation type.

Save all these changes and restart the server.

Explorer time!

Time to take our mutation for a spin! Back in Sandbox Explorer, we'll create a new workspace tab.

In the Documentation panel, let's navigate back to the root of our schema. Beside Query, we can see the Mutation type.

Let's add the addItemsToPlaylist field and all the subfields inside it. For the playlist subfield, select the name for now.

Run the mutation.

Much like query responses, our mutation response followed the same shape as our mutation!

Practice

Key takeaways

• Mutations are write operations used to modify data.
• Naming mutations usually starts with a verb that describes the action, such as "add," "delete," or "create."
• It's a common convention to create a consistent response type for mutation responses.

Up next

We'll learn best practices for mutation inputs and return real data.