liveBook · Manning

GraphQL mutation

As explained in Grokking Software Architecture

A GraphQL operation that requests a change to server-side data or state.

A mutation changes server-side data. Because GraphQL sends reads and writes over HTTP POST, the HTTP verb alone cannot make a mutation safe to retry. If a payment request times out, retrying it without protection could charge the customer twice. section 6.4.2

For safer retries, the client sends a unique idempotency key with the mutation. The server records the key when it processes the payment; if the same key arrives again, it skips the payment and returns the original success response. section 6.4.2

Listing 6.3 GraphQL Mutation with Idempotency Key
# The Client sends the mutation with a unique key
mutation {
  processPayment(
    amount: 50.00, 
    idempotencyKey: "a1b2c3d4-e5f6-7890-1234-56789abcdef0"
  ) {
    status
    transactionId
  }
}

The payment example includes an amount, a unique idempotency key, and fields requested in the response. section 6.4.2

How Grokking Software Architecture covers it

How deep it goes
Explains the duplicate-payment risk and a key-based retry process, without detailing implementation internals.
Examples
Uses a payment mutation for 50.00 and describes how a retry could charge the customer twice.
What you can do after
Apply an idempotency key to a mutation so retries can return the original success instead of repeating the payment.
How it connects
Connects GraphQL mutations with HTTP POST, GraphQL queries, and idempotency keys.

Also explained in

Compare how 3 books explain GraphQL mutation →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Grokking Software Architecture. The section links point to the parts of the book it draws on.