A Beginner’s Dive into GraphQL — Part 4— GraphQL Directives and Mutations

We have discussed basic query of GraphQL in Part - 1, Part - 2, and Part - 3 of this GraphQL series. Today, we will dive deep into little advance mode to discuss GraphQL Directives and Mutations.

Directives

It is so much comfort to dynamically change the query and ultimately result in the GraphQL Variables. It allows us not to use string Interpolation with every query and just change the Variables to get the different result. GraphQL gives us much more comfortable than this. It gives us Directives. In simple language, Directives allow us to either send a request with the parameters of the query through the Variables to the server or do not include that parameter while sending a request to the server.

Let’s see the following example of a Query and a Variables for the better understanding:

query Author($author: Author, $withBooks: Boolean!) {
  author(name: $author) {
    age
    books @include(if: $withBooks) {
      title
    }
  }
}
{
  "author": "Krish Williams",
  "withBooks": false
}

The response you will get from the server may look like this:

{
  "data": {
    "author": {
      "age": 35
    }
  }
}

If we pass true for withBooks, you may get response from server as following:

{
 “data”: {
  “author”: {
   “age”: 35,
   “books”: [
        {
         “title”: “GraphQL - No REST Architect”
        },
        {
        “title”: “JavaScript - Inside Out”
        }
     ]
   }
 }
}

A directive can be attached to a field or fragment inclusion and can affect the execution of the query in any way the server desires. The core GraphQL specification includes exactly two directives, which must be supported by any spec-compliant GraphQL server implementation:

• @include(if: Boolean) Only include this field in the result if the argument is true.
• @skip(if: Boolean) Skip this field if the argument is true.

Directives can be useful to get out of situations where you otherwise would need to do string manipulation to add and remove fields in your query.

Mutations

We spoke a lot in last few posts about data fetching in GraphQL. But any data platform should not only for fetch data but it should also allow mutations on the server. So does the GraphQL.

GraphQL documentation has following words to describe Mutation:

In REST, any request might end up causing some side-effects on the server, but by convention it’s suggested that one doesn’t use GET requests to modify data. GraphQL is similar - technically any query could be implemented to cause a data write. However, it's useful to establish a convention that any operations that cause writes should be sent explicitly via a mutation.

In simple language, the difference between a mutation and a query is the word mutation itself. You can also pass a simple GraphQL query and it will have a side effect just like a mutation. Just like in rest API, we prefer to use POST keyword instead of GET for the mutations on the server, in GraphQL we prefer word mutation to our mutations separate. That does not mean it is not important. In fact, this is one of the more important separations of concern.

So, when you do anything that will change the data, call it a mutation. Also, when you name your Mutations, try to name your mutation verb first. Your mutation represents an action on your server. So start with an action word that best describes what the mutation. Names like createPost, updateComment, and upvotePost are preferable names for Mutation.

There’s one important distinction between queries and mutations, other than the name: While query fields are executed in parallel, mutation fields run in series, one after the other. This means that if we send two updateComments mutations in one request, the first is guaranteed to finish before the second begins, ensuring that we don’t end up with a race condition with ourselves.

Just like GraphQL queries, we can ask for the nested fields in server response if the mutation field returns an object type. This can be useful for fetching the new state of an object after an update. Let’s look at a simple example mutation:

mutation CreateReviewForTheBook($book: Book!, $review: ReviewInput!) {
  createReview(book: $book, review: $review) {
    stars
    commentary
  }
}
{
  "book": "Fundamentals of GraphQL",
  "review": {
    "stars": 5,
    "commentary": "This is a great book for a complete understanding of GraphQL!"
  }
}

The response you receive from the GraphQL the server may look like this:

{
  "data": {
    "createReview": {
      "stars": 5,
      "commentary": "This is a great book for a complete understanding of GraphQL!"
    }
  }
}

That’s it for the GraphQL Directives and Mutations. Any suggestion or question on this article, please feel free to write me at hima.chhag@gmail.com or in the comment section below.

Happy Coding!

• A Beginner’s Dive into GraphQL — Part 1
• A Beginner’s Dive into GraphQL — Part 2
• A Beginner’s Dive into GraphQL — Part 3