Designing GraphQL Schemas: Mutations

As part of my learning in public drive for the new year, I thought I'd write down some notes as I take in Nik Graf's egghead.io course on Designing GraphQL Schemas.

This will be a series of short posts based on my notes. I'm continuing here with some notes on mutations.

Naming

It is a good convention to begin the mutation's name with a verb to describe the change it makes, e.g. deleteRecords, createPage, updateItem. Use camel case.

Input

It is best to provide a single, non-nullable input object to a mutation. This makes it easier to add arguments.

The convention for an input is it should follow the name of the mutation but with the postfix Input. So the input for a createPage mutation would be CreatePageInput. Use Pascal case because they define an input type.

For example:

input CreatePageInput {
 id: ID!
}

Payload

A mutation should also return a single, non-nullable payload object. A payload can then return any data relevant to the enacted mutation.

The convention for a payload is it should again follow the name of the mutation but with the postfix Payload. So the payload for a createPage mutation would be CreatePagePayload. Use Pascal case because they define a type.

For example:

type CreatePagePayload {
 page: Page
}

Usage

Here is how we would put all those parts together in our schema:

type Mutation {
 createPage(input: CreatePageInput!): CreatePagePayload!
}

And here is how we would use the mutation:

mutation CreatePageMutation($input:CreatePageInput!) {
  createPage(input: $input) {
    page {
      title
    }
  }
}