Idempotency

A button that sets the volume to 20 behaves differently from one that increases it by 1. Repeating the first command leaves the volume at 20; repeating the second keeps increasing it. Idempotence, often called idempotency in API design, is the property that applying an operation again preserves the result of applying it once.

Server developers often encounter the term through duplicate payments or request keys, but it comes from mathematics. Algebra concerns repeated operations, HTTP concerns the intended effect of requests, and business APIs add contracts for identifying and processing the same operation again. These uses are connected, though each requires us to specify what repeats and what counts as the same result.

A name from powers in algebra

Section 25 of Benjamin Peirce's Linear Associative Algebra uses the word idempotent and states that, unless otherwise specified, it will mean A² = A. The accompanying term nilpotent describes an expression whose power becomes zero. These names distinguish algebraic objects by what repeated multiplication produces. This is Benjamin Peirce, the father of Charles Sanders Peirce, who is also known for his work in philosophy.

(Original source)

This crop is from printed page 8, PDF page 20, of the 1882 edition. Its preface says that lithographed copies circulated in 1870, so the earlier circulation and the edition shown here should be distinguished. The passage mentions higher powers before adopting the square as its default. The image reproduces a public-domain scan. Edition record, preface.

For composition of a function f from a set to itself, the corresponding condition is f(f(x)) = f(x) for every input x. Applying the function to its own result leaves that result unchanged. Absolute value has this property on integers: the first application has already removed the negative sign. Squaring takes 2 to 4 and then 16, so it is not idempotent.

def square(x):
    return x * x

assert abs(abs(-3)) == abs(-3)
assert square(square(2)) != square(2)
print(abs(-3), square(2), square(square(2)))  # 3 4 16

This runs in Python 3. Calling square(2) repeatedly and getting 4 each time shows determinism. The example instead applies square to its previous result. Keeping repeated calls with the same input separate from composition helps distinguish pure functions from idempotent ones.

The term also applies to binary operations, such as set union: A ∪ A = A. Here the law compares an operation whose two operands are equal, rather than function composition. The shared relationship is that repetition adds no further change to the result.

Programs apply operations to state

For a command, we often need to compare changes in state rather than return values. If s is a state and T is the command's state transformation, the condition is T(T(s)) = T(s). Setting the volume is an example.

Both rows start at volume 5 and apply their respective command twice. This explanatory diagram compares state transformations.

def set_volume(state):
    return {**state, "volume": 20}

def increase_volume(state):
    return {**state, "volume": state["volume"] + 1}

initial = {"volume": 5}
assert set_volume(set_volume(initial)) == set_volume(initial)
assert increase_volume(increase_volume(initial)) != increase_volume(initial)
print(set_volume(initial), increase_volume(increase_volume(initial)))

The functions return new dictionaries to make the state transformations visible; they do not operate an audio device. Both are written as pure functions, but only one is idempotent. A command that writes a setting to a real device can have side effects while remaining idempotent with respect to the observed volume.

These properties answer different questions.

Negating a boolean twice restores its original value, which differs from the value after one negation. Also, an operation that happens to preserve a particular input need not be idempotent over its full domain: squaring leaves both 0 and 1 unchanged.

Communication failures give us a reason to repeat

Remote calls create a practical reason to send the same command again. If a server saves an order but its response disappears, the caller may be unable to distinguish an undelivered request from a completed request whose reply was lost. Retransmission helps recover from communication failure, but repeating an order-creation effect can create another order.

Birrell and Nelson's 1984 paper Implementing Remote Procedure Calls, section 3.2, describes call identifiers and sequence numbers for recognizing duplicate call packets. Retransmission and duplicate execution were already separate concerns in this RPC design. This is a historical example of duplicate suppression, rather than evidence that the paper invented idempotence. Publication record, paper PDF.

The 1997 HTTP/1.1 specification, RFC 2068, distinguishes safe methods from idempotent methods in section 9.1. Asking for retrieval and repeating a request without accumulating its effects are different properties. The distinction informs which requests a client can retry after a connection fails. RFC 2068 sections 8.1.4 and 9.1.

RFC 7231 in 2014 and RFC 9110 in 2022 retain this distinction. The table describes the semantics promised by the methods; using a method name still requires the server to implement that promise. RFC 7231 section 4.2.

A first DELETE may return 204 and a later one 404 while preserving the intended deletion effect. RFC 9110 permits per-request logging or revision history and explains that responses to idempotent requests may differ. Its comparison concerns the intended server effect. RFC 9110 section 9.2.2.

Why order creation needs a request identity

A command to add an order normally creates another order each time it runs. Such an API can identify a repeated attempt at the same operation and avoid creating its effect again.

(Original source)

This is the original diagram on PDF page 4, printed page 3, of Malcolm Featonby's Making retries safe with idempotent APIs. It illustrates an API contract that keeps the same identifier after losing a response. It concerns request deduplication, one application of the broader concept. © Amazon Web Services.

The article favors an explicit caller-provided identifier over assuming that matching request bodies mean matching intentions. A customer may legitimately order the same item and quantity twice. Caller scope, reuse of a key with different content, and record retention all affect what the API recognizes as the same operation. AWS article.

There are two design choices here. An operation can specify the desired state directly, or it can remain an additive operation whose repeated requests are controlled by records. The latter requires the effect and its record to be handled atomically. A local database transaction alone cannot cover an external payment service's effect. Whether to reuse a response is another part of the API contract.

Idempotence is a property of repeated effects; deduplication is a technique for recognizing an operation already seen. Within its retained records and other stated assumptions, deduplication can help provide idempotent behavior. Expired records and effects in other systems require further guarantees. An “exactly once” claim likewise needs to identify whether it concerns delivery, execution, or a business effect.

What stays the same in each context

As this algebraic property is used in communication and business processing, the scope of equality and the mechanism that provides it become part of the explanation. Specifying the repeated operation and the observed effect makes the guarantee clear. Preventing duplicate orders is one application; request keys and stored results are chosen mechanisms for providing it.