Comments

What Are GraphQL Mutations

GraphQL Mutations

GraphQL is a query language for your API. It was open-sourced by Facebook in 2015 and ever since then gained immense popularity as an alternative to REST. In this blog post, we are going to learn what a GraphQL Mutation is all about, and even write a few ourselves.

Introduction

In the REST world you might be familiar with GET and POST requests. Similarly, in GraphQL when a client asks for data from the server it is called a query and when the client writes or updates data to the server it is termed as a mutation.

Mutations in GraphQL are used to make changes to the data.

To learn mutations let’s use the GraphQL explorer and run some mutations against the GitHub’s public GraphQL API. You can follow along this post by clicking the link below. Make sure you are signed into your GitHub account to follow along.

https://developer.github.com/v4/explorer/

On the GitHub GraphQL explorer, we can start typing our queries and mutations on the left side and hit play to see the JSON response on the right side. We can also browse through the documentation of the API on the right side. The explorer is a great way to write, validate and test queries and mutations.

GraphQL Mutations

Alright, we are all set to write our first mutation. You can browse the mutations that are available to us, from the Documentation Explorer on the right. Something interesting to note is that, the GraphQL Schema is strongly-typed and hence generates its own documentation without any manual work from developers. Isn’t that nice?! It provides great API documentation without any manual effort. Alright back to mutations.

There are plenty of mutations that are available to us in this API and I am going to pick the createRepository mutation. As the name suggests, the client can use this mutation to create a new repository for the user on GitHub. Let’s dive into writing this mutation.

Define an Operation Name

mutation myFirstMutation {
  // ..
}

Whenever you write a mutation you define it with a unique operation name. Here we use the keyword mutation and give our mutation an operation name myFirstMutation. 

Explore The Documentation

I am now going to browse through the documentation for the createRepository mutation. It looks like the createRepository mutation takes in an argument of type CreateRepositoryInput. Clicking on it will provide me more information on what this type contains.

In GraphQL, the exclamation mark (!) on a type indicates that the field cannot be null. In this case the createRepository mutation is expecting an argument CreateRepositoryInput! and it cannot be null.

Pass Variable Input Arguments

mutation myFirstMutation ($input: CreateRepositoryInput!){
  createRepository(input: $input) {
    clientMutationId
  }
}

I have now passed an input argument of type CreateRepositoryInput! The input argument here can be any variable that the client can pass. The input variable is represented as $input. Now we are writing our createRepository mutation and passing the input variable down to it.

Define Input Variable

Since we decided to pass a variable input to the mutation, it is time to define it. In the GraphQL explorer, you can define input variables in the Query Variables section on the left. In our case the input needs to be of type CreateRepositoryInput and it requires a name and visibility fields to perform the mutation.

{
  "input": {
    "clientMutationId": "102020",
    "name": "My New Repository",
    "visibility": "PUBLIC"
  }
}

We are giving a name for the repository as “My New Repository” and setting the visibility to be public. I am also passing a clientMutationId. This is not required field for our mutation. It can be any random number that acts as the unique Id for this mutation.

Run the Mutation

Now we are all set. We can run our mutation and it should return back a successful JSON. This is the JSON response I receive back. It doesn’t tell us much, but it indicates that the mutation executed at the clientMutationId that we defined in the input variable.

{
  "data": {
    "createRepository": {
      "clientMutationId": "102020"
    }
  }
}

Validate Mutation

Since we are using live production data from GitHub to run our mutations, we can validate this mutation easily. If you were following along with me this far, if you go to your GitHub profile and look at your repositories, there should be a new repository created.

Isn’t that neat! Well, we can’t always validate mutations by checking the user interface. To validate this mutation without the UI, we can write a simple query to make sure the new repository was created.

query validate{
  user (login:"adhithiravi") {
    repositories(last: 1) {
      nodes {
      	name
      }
    }
  }
}

This query above, queries my user on GitHub and queries for the most recently created repository. This query can validate if the mutation occurred as expected or not. The query result should return the name of the new repository I created.

Resources

That’s a wrap folks! I hope this article shed some light on GraphQL mutations and using them. I encourage you to play around with some GraphQL APIs to learn this better. Here is a list of other public GraphQL APIs that are available to everyone.

https://github.com/APIs-guru/graphql-apis

If you are looking to learn a big picture overview of GraphQL, checkout my course on Pluralsight titled GraphQL : The Big Picture

Here are some other GraphQL articles from me for further reading:

Why Should I Pick GraphQL?

REST vs. GraphQL

As always, if you enjoyed this post, please share it. You can follow me on twitter @AdhithiRavi for more updates.

 

Adhithi Ravichandran is a Software Consultant based in Kansas City. She is currently working on building apps with React, React Native and GraphQL. She is a Conference Speaker, Pluralsight Author, Blogger and Software Consultant. She is passionate about teaching and thrives to contribute to the tech community with her courses, blog posts and speaking engagements.
Tags: ,

Leave a Reply

Connect with Me
  • Categories
  • Popular Posts

    %d bloggers like this: