graphql.tar.gz

graphqlspa

graphqlcodewidget

In this course, you will learn what exactly GraphQL is, how to design a robust and scalable API with it, and how to implement it in NodeJS.

You’ll start by running through the pros and cons of GraphQL in order to get a feel for its limitations and what its applications are. You’ll then take a brief look into the REST vs GraphQL debate and understand the reasons for and against both.

In the latter half of the course, you’ll explore things like GraphQL types, schemas, and mutations. In the last few sections, you’ll take what you’ve learned and make a GraphQL API in Node while scaling it for consistency.

Up and running with Node and GraphQL

# Introduction

So, what’s a mutation? It sounds quite intimidating. Luckily, they are fairly straightforward.

A mutation is just another type of field in a GraphQL schema, the same as a query. In this case, though, a mutation is a standard way to modify server-side data.

In theory, _any_ GraphQL operation could alter server-side data, but the convention is to use the mutation field type to accomplish this.

As the GraphQL specification notes, REST APIs do not prevent you from modifying data via a `GET` request. But in practice, the convention is to do this with a `POST`. The same applies in GraphQL. To modify data, use a mutation.

## The structure of a mutation

Mutations have a similar structure to queries in that they consist of the field name and the arguments that it accepts.

For example:

```graphql
mutation createUser(email: String!, password: String!) {
   createUser(email: $email, password: $password) {
      id
      email
      password
}
```

In theory, you can return a field from a mutation, but a better practice is to return a Payload Type, which is a type dedicated to providing the correct shape for a mutation response.

In the example above, we are creating a user. We might create the following response type:

```graphql
  type RegistrationMutationResponse {
    message: String!
    user: User
  }
```

This would allow us to provide a custom success message we could display on the front-end, as well as all the fields available on our newly-registered user. 

We can go a step further for a cleaner schema design and create a specific interface for a mutation response like this:

```graphql
  interface MutationResponse {
    code: String!
    success: Boolean!
    message: String!
  }
```

This means that every mutation response type that implements the above mutation provides a minimum of these fields. This gives us a very consistent API experience. We always know that we will get a code, success boolean, and message back, along with anything else.

For example, we could then update our `RegistrationMutationResponse` to become:

```graphql
  type RegistrationMutationResponse implements MutationResponse {
    code: String!
    success: Boolean!
    message: String!
    user: User
  }
```

## What needs a mutation?

Now that you know how to make a basic mutation, you must figure out how many mutations to make. Do you need to make a single mutation per field, or should you do a mutation per type? Maybe something in between?

When talking about mutations, it is best to think about whether they are _fine-grained_ or _coarse-grained_.

Generally, this means that a mutation can be very wide and update a lot of things, or a mutation can be very specific and only apply to a single field or entity.

What you decide is generally driven by how you anticipate it being used. A good rule of thumb is to handle creating entities as a broader mutation, but keep updates as individual items.

This approach gives you plenty of flexibility, but it does not create frustrating scenarios when it comes to trying to create entities and needing to handle multiple outcomes at once. Instead, an entity either does or does not exist. For example, you would not want to have a scenario where the blog title was saved, but the body was dropped due to a validation issue. It should be all or nothing.

On the other hand, you would most likely want to update a blog’s title or body on an individual basis without needing to submit the entire blog entity each time. This is where finer-grained mutations shine.

# Recap

In this lesson, you learned the basics of mutations and should understand:

- What a mutation is and how to write one
- How to structure a mutation in your schema
- How to write reusable mutation response types to provide flexibility in your schema design
- When to use a coarse-grained, and fine-grained mutation, and the trade-offs involved in each

Learn what a mutation is, how it differs from queries, and how best to design them.