Writing Idempotent Code: A Guideby@bezgin
615 reads
615 reads

Writing Idempotent Code: A Guide

by Iurii BezginOctober 28th, 2023
Read on Terminal Reader
Read this story w/o Javascript
tldt arrow

Too Long; Didn't Read

Idempotence is a property of some operations such that no matter how many times you execute them, you achieve the same result. It is essential for several reasons: Error Recovery, Concurrency, User Experience, and Payment Processing. How can you write idempotent code?
featured image - Writing Idempotent Code: A Guide
Iurii Bezgin HackerNoon profile picture


When developing software, it’s crucial to write reliable code, especially when working with distributed systems and microservices. One way to achieve this reliability is through idempotence. But what does “idempotent” mean, and how can you write idempotent code?

What Is Idempotence?

Idempotence, in programming and mathematics, is a property of some operations such that no matter how many times you execute them, you achieve the same result.

For example, pressing the “stop” button on your alarm clock is idempotent. Whether you press it once or five times, the alarm remains muted. On the other hand, pressing the “volume up” button is not idempotent, each press increases the volume.

Why Is Idempotence Important?

Idempotence is essential for several reasons:

  • Error Recovery: If a system crashes during an operation, you can safely retry the operation without worrying about adverse effects.

  • Concurrency: In a distributed system, multiple nodes might try to perform the same operation. Idempotence ensures that the end result remains consistent.

  • User Experience: Users can refresh a page or click a button multiple times without unintended side effects.

How to Write Idempotent Code

Clear the Result Before Updating It

Delete data from tables and reassign values to variables before performing operations. If you want to add only new data, then purge the partition you are working with.

ALTER TABLE table_name DROP IF EXISTS PARTITION(year = 2022, month = 12);

INSERT INTO TABLE table_name PARTITION (year = 2022, month = 12)
SELECT * FROM another_table

WHERE some_condition;

Database Transactions

Use database transactions to ensure that a series of operations either completely succeed or fail. This ensures that the database remains in a consistent state, even if an operation is retried.


UPDATE accounts SET balance = balance - 1000 WHERE account_id = 1;

UPDATE accounts SET balance = balance + 1000 WHERE account_id = 2;


Idempotency Keys

In situations like payment processing, you can use idempotency keys to make operations idempotent. When a client sends a request, it includes a unique idempotency key. The server checks if a request with that key has already been processed.

If it has, the server returns the previous response instead of performing the operation again.

registrations = {}
def register_user(idempotency_key, user_data):
    if idempotency_key in registrations:
        return registrations[idempotency_key]
    # App logic here
    registrations[idempotency_key] = "User registered"
    return registrations[idempotency_key]

Use Safe HTTP Methods for Web Services

If you’re building a RESTful API, use HTTP methods that are inherently idempotent, like GET, PUT, DELETE, and HEAD. Avoid using POST or use idempotency keys as in the example above.

Item Idempotence

For operations like “add to cart”, you can make the operation idempotent by specifying the final state rather than the change. For example, instead of “add one item” the operation could be “set the number of items to 1.”

# Server-side Python code
cart = {}

def set_cart_item(item_id, quantity):
    cart[item_id] = quantity

Use State Machines

State machines can also be useful for ensuring idempotency. They define the possible states of a system and the transitions between them. By checking the current state before performing an operation, you can ensure that the operation is idempotent.

jobs = {}

def run_job(job_id):
    if jobs[job_id] == "queued":
        jobs[job_id] = "running"
        #Start the job

Testing for Idempotence

Testing for idempotence is straightforward. Perform the operation once, and record the outcome. Then, perform the operation multiple times, and compare the outcomes. They should be the same.

def test_idempotence_delete():
    initial_result = update_user(1, {"name": "Yuri", "age": 30})
    repeat_result = update_user(1, {"name": "Yuri", "age": 30})
    assert initial_result == repeat_resultpy

Note that in a distributed system, testing for idempotence can be more complex due to issues like network latency, failures, etc.


Writing idempotent code is not just a best practice but often a necessity in modern software development. It makes your applications more robust, easier to understand, and less prone to bugs.

By understanding the core principles and implementing the strategies mentioned above, you’ll be well on your way to writing more reliable code.

Also published here