Skip to content
API Design Learn/GraphQL Foundations
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Mutations Done Right

3 min read

You'll learn to

  • -Give each mutation one dedicated input type, so its signature stays stable as fields are added
  • -Name mutations with one verb-noun pattern, like createUser, updateUser and deleteUser
  • -Return enough from a mutation for the client to update its screen with no follow-up query

Mutations are GraphQL's way of changing data, the counterpart of REST's POST, PUT, PATCH and DELETE. Like queries, they live on their own root type. A few conventions separate mutations that are pleasant to use from ones that fight every client.

An Analogy: The Order Form and the Receipt

When you hand a shop a single order form, it can add new optional boxes later without changing how you hand it in. When the shop hands you back a receipt that lists exactly what changed, you can update your own list without going back to ask. An input type is the order form, and a good payload is the receipt.

Input Types, Not Raw Arguments

A dedicated input type instead of a long, unstructured argument list
input CreateUserInput {
  name: String!
  email: String!
  age: Int
}

type Mutation {
  createUser(input: CreateUserInput!): User!
}

A mutation could take each field as a separate top-level argument, such as createUser(name: String!, email: String!, age: Int): User!. A dedicated input type keeps the signature stable as fields are added. A new optional field on the input type does not change the mutation's own signature, but a new top-level argument does. It is the GraphQL version of the DTO discipline from the REST modules.

Naming: Verb-Noun, Consistently

A consistent verb-noun naming convention across every mutation
type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
  deleteUser(id: ID!): DeleteUserPayload!
}

Just as REST benefits from consistent resource names, mutations benefit from one verb-noun pattern (createX, updateX, deleteX) used everywhere. A client can predict a mutation's name from the pattern, instead of looking each one up.

Returning Enough to Avoid a Follow-Up Query

A mutation payload that gives the client what it needs to update local state
type DeleteUserPayload {
  deletedId: ID!
  success: Boolean!
}

mutation {
  deleteUser(id: "42") {
    deletedId
    success
  }
}

A mutation should return enough for the client to update its own cache or screen without another query. createUser returning the full new User, including its server-assigned id, lets the client add it to a list directly. deleteUser returning the deleted id tells the client exactly which item to remove. That is why even a delete usually returns a small payload in GraphQL, where REST would send an empty 204. The demo shows a client keeping its screen up to date from the payloads alone.

Press Run: the payloads are all the client needs, with no extra query

This matters most for clients with a normalized cache, such as Apollo Client or Relay. They update automatically from the ids in a mutation response, so leaving ids out forces a wasteful follow-up query just to keep the screen in sync.

Interview Signal is part of Pro

See a real weak answer next to a real strong one for this exact topic.

Quiz is part of Pro

Test what you just read with a short quiz, and bank the XP.

Ready to Build This?

Design Mutation Station in the API Design Lab's GraphQL Mastery act.

Discussion0

Join the Discussion

Sign in to leave comments, reply to others, or like insights.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!