Interactive Guide to GraphQL Mutations

This guide is a continuation of our interactive series on GraphQL. In the previous guides, we have already talked about GraphQL Queries, Fields, Arguments and GraphQL Aliases and Variables. This guide will cover the use of Mutations in GraphQL.

Introduction

In REST APIs, we generally use the GET method for fetching data and PUT, PATCH, etc, to manipulate data. A similar distinction exists in GraphQL, which lets you perform two types of operations: queries and mutations. Queries are used for fetching data, while mutations are more about modifying data.

So from a REST point of view, GraphQL Queries are equivalent to GET and POST requests while mutations are comparable to methods like DELETE, PUT, PATCH, etc.

Mutations

Mutations allow us to modify or change the data on the backend. Whenever you want to add, update, or delete data, you will have to specify the request as a mutation.

Mutations are pretty similar to queries in terms of structure other than the "mutation" keyword.

Adding Data

Consider the following example in which the query fetches a user while the mutation creates a new user.

graphql
Copy
# Query
query getUser($input: ID!) {
	user(id: $input) {
		id
		name
		email
	}
}
# Mutation
mutation AddNewUser($userInput: CreateUserInput!) {
	createUser(input: $userInput) {
		id
		name
	}
}

The mutation AddNewUser expects a variable input of type CreateUserInput having required parameters for creating a new user. It needs to be defined in the variables object like this:

json
Copy
{
	"userInput": {
		"name": "John Doe",
		"username": "johndoe",
		"email": "johndoe@gmail.com",
		"phone": "12345",
		"website": "johndoe.com"
	}
}

Here is the response we get for this mutation:

json
Copy
{
	"data": {
		"createUser": {
			"id": "11",
			"name": "John Doe"
		}
	}
}

As you can see, like queries, mutations also return the data specified in the fields. Play around with the following interactive component to see how mutations work:

Updating or Deleting Data

Like above, you can use mutations to update data on the server side. The following mutation will update the user using the given id.

graphql
Copy
mutation UpdateUser($inputID: ID!, $userInput: UpdateUserInput!) {
	updateUser(id: $inputID, input: $userInput) {
		id
		name
	}
}

json
Copy
// Variables object
{
	"inputID": "2",
	"userInput": {
		"name": "John Doe",
		"username": "johndoe",
		"email": "johndoe@gmail.com",
		"phone": "12345",
		"website": "johndoe.com"
	}
}

Here is the corresponding response of this mutation:

json
Copy
{
	"data": {
		"updateUser": {
			"id": "2",
			"name": "John Doe"
		}
	}
}

The last thing to note is that each mutation must be defined within the GraphQL API type definitions. For instance, the createUser and updateUser mutations are defined in the API's schema as follows:

graphql
Copy
type Mutation {
	createUser(input: CreateUserInput!): User
	updateUser(id: ID!, input: UpdateUserInput!): User
}

So if you are consuming a GraphQL API, take a look at its schema to see how you can write mutations.