Mutations Done Right
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
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
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
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.
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.
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.
No comments yet. Be the first to start the thread!