# Idempotency — REST API Design

Source: https://www.geekswithgeeks.com/en/restapi/api-idempotency

> Why calling the same operation twice should be safe.

## Same result, no matter how many times

An operation is **idempotent** if calling it once has the same effect as calling it many times. `PUT /orders/482` (replace with this exact body) and `DELETE /orders/482` are idempotent — the resource ends up in the same state either way.

## Why it matters for retries

Networks drop responses, not always requests — a client that times out doesn't know if the server actually processed it. If the operation is idempotent, retrying is always safe. `POST` (usually creates) is the classic non-idempotent case.

## Making POST safe to retry

An `Idempotency-Key` header lets the client supply a unique id per logical operation; the server stores the result and replays it if the same key arrives again — common in payment APIs.

```http
POST /payments HTTP/1.1
Idempotency-Key: 6c9a1e4e-3f21
Content-Type: application/json

{ "amount": 500, "currency": "INR" }
```

## PATCH usually isn't idempotent

A PATCH like `{ "increment": 1 }` gives a different result each time it's applied. Prefer PATCH bodies that set absolute values when idempotency matters.