A Basic Intro to Mutations in GraphQL

Introduction

This article is part 4 in a 4-Part Series - A Basic Intro to GraphQL. The purpose of this article is to provide a basic intro to the concept of mutations in GraphQL. By the end of this article, you should have a basic understanding of mutations in GraphQL and a runnable example of mutations in your local environment.

What is a Mutation in GraphQL?

In GraphQL, a mutation is an operation that allows you to Create, Update or Delete server-side data.

Local Environment Setup

1. Download the Demo App
2. Run npm install then run npm start
3. Navigate to Apollo Studio Explorer at https://localhost:4000/graphql

Validation Query

The following query can be used to validate that the test user that we'll be using for the following examples does not yet exist:

query GetUserFields($userId: ID!) {
  user(id: $userId) {
    id
    name
    email
  }
}        

{
  "userId": "3"
}        

Create Mutation

To create a new user, copy/paste the following mutation into the Operation panel in Apollo Studio Explorer:

mutation CreateUser($name: String!, $email: String!) {
  createUser(name: $name, email: $email) {
    # fields to return in the createUser response object
    id
    name
    email
    createdAt
    updatedAt
    posts {
      id
      text
      likes
      createdAt
      updatedAt
    }
    # end of fields to return in the createUser response object
  }
}        

Copy/paste the following json into the Variables panel of Apollo Studio Explorer:

{
  "name": "Test User",
  "email": "[email protected]"
}        

The Response panel in Apollo Studio Explorer will display the createUser response object with the fields populated according to the submitted mutation configuration. So there is no need to re-run the original Validation Query to validate the existence of the user.

Update Mutation

Now let's update the user that we just created with an Update mutation:

mutation UpdateUser($id: ID!, $name: String, $email: String) {
  updateUser(id: $id, name: $name, email: $email) {
   # fields to return in the updateUser response object
    id
    name
    email
    createdAt
    updatedAt
    posts {
      id
      text
      likes
      createdAt
      updatedAt
    }
    # end of fields to return in the updateUser response object
  }
}        

{
  "id": "3",
  "name": "Test User Update",
  "email": "[email protected]"
}        

The Response panel in Apollo Studio Explorer will display the updateUser response object with the fields populated according to the submitted mutation configuration. So there is no need to re-run the original Validation Query to validate that the user was updates.

Delete Mutation

Now let's delete the user that we just created with a Delete mutation. Copy/paste the following code into the Operation panel of Apollo Studio Explorer:

mutation DeleteUser($id: ID!) {
  deleteUser(id: $id) {
    id
    successMessage
  }
}        

Copy/paste the following json into the Variables panel of Apollo Studio Explorer:

{
  "id": "3"
}        

In the Response panel, the success message in the deleteUser response object should say "User successfully deleted."

Conclusion

The purpose of this article was to provide a basic introduction to the concept of mutations in GraphQL. You should now have a basic understanding of mutations in GraphQL and be able to configure and run mutations and properly interepret the responses.