Software ArchitectureAtlas

Software Architecture Atlas

Gain an overview. Understand the connections.

ConceptChapter II · Communication · Building block 5 of 9

Idempotency

Idempotence keeps the business effect of the same logical operation stable upon repetition. A unique identifier connects all attempts with the stored result.

By Michael Meierhoff · Meierhoff Systems

  1. KeysCombine all attempts of an intention.
  2. Saved resultRepetition gives the same result.
  3. Same intentionOther content is a conflict.

Context

Why this is important

Repeats are normal for lost answers. Without Idempotence, the same call can act twice, here a double load. Deciding if and when to repeat is a matter for Retry.

This building block explains safe repetition of the same operation. For the decision on re-testing, see Retry.

At a glance · Repeat with the same key

The service checks the key in the keystore and executes the same request only once, even if it is repeated.
Shop example · Playing through scenarios

A burden despite repetition

The payment module sends B-1042 with the key pay-B-1042 to the external provider. The first answer is lost.

This is how you read the picture

  1. Keys With "pay-B"1042“ the provider recognizes the repetition as the same order.”
  2. Saved result The result memory reports "Z-"9 Already present, the burden remains 1 × 49,90 €.
  3. Same intention Both experiments carry the same key and the same 49,90 €Only then will it be considered a duplicate.
Response to the first attempt
Keys
  • runningPayment moduleAnswer arrived, no retry
  • runningPayment providerLoaded once
  • NoteResult storeis not needed
  • runningLoading of B-10421 × 49,90 €

1Loads of B-1042

When the answer arrives, there is no repetition. The key does not show any difference here.

Let the first answer get lost and switch the key. You see how often B-1042 is loaded.

Benefits & limitations

Helps if:

  • A stable key associates retries with the same operation and resolves an uncertain outcome.
  • Atomically linking the key, request and change protects the business effect against concurrent or repeated execution.
  • External effects need their own duplicate detection and status resolution beyond the local database transaction.

Boundaries

  • The key must identify the same intent consistently across all attempts; a new key for each attempt defeats the protection.
  • The stored result needs a retention period and storage space; once it expires, a retry is treated as a new request.
  • Idempotency makes retries safe; Retry decides whether to try again.

In practice

  1. Define a stable identifier for each logical operation and bind it to the unchanged request content. Reusing the key with different content needs an unambiguous conflict response.
  2. Store the key, business change and result to return within the same atomic boundary. A retry then returns the known result rather than triggering a second effect.
  3. Handle external effects using their own duplicate detection or status query. Retry controls attempts; Transactional Outbox safeguards message delivery.
Read the detailed explanation

An operation is idempotent if executing it repeatedly with the same business intent leaves the same state as executing it once. The response data may differ; what matters is the effect on state. Setting a target state can therefore also be idempotent.

A stable key identifies retries as the same logical operation. The key, request fingerprint, business change and retrievable result must be linked atomically; reusing a key with different request content receives a defined conflict response. Uniqueness constraints and a transaction ensure a single change when retries arrive concurrently. External effects fall outside this local atomicity and need their own delivery and recipient strategy.

Retry decides when to try again; idempotency ensures that the same key with the same request identifies the same operation. Transactional Outbox handles subsequent external delivery.

With HTTP, the Idempotency-Key header often carries the key, such as pay-B-1042 in the shop.

Check your understanding

Test yourself in three stages

  1. ReadingCheck in the picture

    How often is B-1042 If the answer is lost and the key is missing?

    View the solution with justification

    Twice, each 49,90 €. With key pay-B-1042 Only once, as Z-9.

  2. ApplyingTransferred to a new situation

    The answer to the first attempt was lost. What does the payment send on the second attempt?

    View the solution with justification

    The same key pay-B-1042 with the same 49,90 €, so that the provider recognizes the existing result.

  3. EvaluateWeighing an alternative

    Should the payment generate a new key for each attempt? How do you weigh up?

    View the solution with justification

    New keys act independently, but the provider cannot recognize the repetition as the same intention and could charge again. The fixed key protects against double effect.

Explore further

These building blocks continue the thoughts of this page.

OperationsRetryRetry repeats a failed operation within defined limits and conditions.Opening OperationsTimeoutA timeout limits waiting time. Here you learn how the caller handles the resulting state.Opening CommunicationAPI contractsAPI contracts define data, meaning and observable interface behavior as binding rules.Opening

References

Continue on the learning path

Next in Communication & APIs: Transactional Outbox.

9 Building blocks

Continue withTransactional Outbox