What is idempotency in API design

Short answer

Idempotency guarantees that making the same API request multiple times produces the same result as making it once, which is essential for safe retries.

How it works

An idempotent operation leaves the system in an identical state whether executed once or many times. GET, PUT, and DELETE are naturally idempotent because repeated reads or replacements do not compound changes. POST is typically not idempotent because each call may create a new resource. To make non-idempotent operations safe, APIs can require clients to send an idempotency key that the server uses to detect and deduplicate duplicate requests.

Example

A payment API accepts an idempotency key in the header. If the network times out and the client retries with the same key, the server recognizes the duplicate and returns the original transaction result instead of charging the customer twice.

Why it matters

Idempotency enables robust distributed systems where network failures and retries are inevitable. Without it, duplicate operations can corrupt data, process duplicate payments, or create inconsistent states.

Example

curl -X GET https://api.example.com/users   -H "Accept: application/json"   -H "Authorization: Bearer $TOKEN"

This curl command demonstrates a standard GET request with headers for content negotiation and bearer token authentication.