name: graphql-mutations
description: GraphQL mutation design including payload patterns, field-specific errors, input objects, and HTTP semantics. Use when designing or implementing GraphQL mutations.
GraphQL Mutations
Expert guidance for designing effective GraphQL mutations.
Quick Reference
Pattern
Use When
Structure
Result payload
All mutations
mutationName(input): MutationNamePayload!
Field-specific errors
Validation failures
errors: [FieldError!]! in payload
Input objects
Complex arguments
input: MutationNameInput!
Noun + Verb naming
State changes
createUser, deletePost, closeCard
Idempotent mutations
Safe retries
Design for repeatable calls
Optimistic UI
Client-side updates
Return predicted result
What Do You Need?
Payload design - Return types, error handling
Input objects - Structuring mutation arguments
Error patterns - Field-specific vs top-level errors
Naming - Mutation naming conventions
Side effects - Handling async operations
Specify a number or describe your mutation scenario.
Always return a payload: Never just a boolean or the object
Use input objects for complex arguments: Don't use many scalars
Field-specific errors in response: Let clients handle per-field failures
Noun + verb naming: createUser, deleteUser, not user
Mutations are POST-only: Never use GET for mutations
Design for idempotency: Safe to call multiple times
Mutation Template
# Input object for complex arguments
input CreateUserInput {
name: String!
email: String!
password: String!
}
# Payload with result and errors
type CreateUserPayload {
user: User
errors: [UserError!]!
}
# Field-specific error type
type UserError {
field: [String!]! # Path to field: ["email"] or ["user", "emails", 0]
message: String!
}
# Mutation definition
type Mutation {
"""
Creates a new user account
"""
createUser(input: CreateUserInput!): CreateUserPayload!
}
Mutation Implementation
// Good: Mutation with proper payload and field errors
func (r *mutationResolver) CreateUser(ctx context.Context, input CreateUserInput) (*CreateUserPayload, error) {
// Validate
var errs []UserError
if input.Name == "" {
errs = append(errs, UserError{
Field: []string{"name"},
Message: "Name is required",
})
}
if !isValidEmail(input.Email) {
errs = append(errs, UserError{
Field: []string{"email"},
Message: "Invalid email format",
})
}
if len(errs) > 0 {
return &CreateUserPayload{Errors: errs}, nil
}
// Create
user, err := r.db.CreateUser(input)
if err != nil {
if errors.Is(err, db.ErrDuplicate) {
return &CreateUserPayload{
Errors: []UserError{{
Field: []string{"email"},
Message: "Email already exists",
}},
}, nil
}
return nil, fmt.Errorf("failed to create user")
}
return &CreateUserPayload{User: user, Errors: []UserError{}}, nil
}
Common Mutation Patterns
Create
type Mutation {
createUser(input: CreateUserInput!): CreateUserPayload!
}
type CreateUserPayload {
user: User
errors: [UserError!]!
}
Update
type Mutation {
updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
}
type UpdateUserPayload {
user: User
errors: [UserError!]!
}
Delete
type Mutation {
deleteUser(id: ID!): DeleteUserPayload!
}
type DeleteUserPayload {
deletedUserId: ID
errors: [UserError!]!
}
State Change (Noun + Verb)
type Mutation {
"""
Closes a card (marks as closed, not deleted)
"""
closeCard(id: ID!): CloseCardPayload!
}
type CloseCardPayload {
card: Card
errors: [UserError!]!
}