Idempotency and Safety

The Concept of Safe Methods

A method is considered 'safe' if it does not change the state of the server or the resource. From a design perspective, this means that executing a safe request should result in no side effects on the data model, such as updating a database row or modifying a file. Safe methods are primarily used for retrieval operations where the goal is to gain information without interference. By adhering to this principle, intermediaries like caches, proxies, and load balancers can optimize traffic flow because they know the server's data remains untouched. If a client mistakenly sends a 'GET' request a thousand times, the server state remains pristine. Understanding this is crucial because it allows architects to treat safe requests as read-only operations that can be automatically retried or cached without hesitation by any network component.

// A safe operation should not change the state of the system
// GET /users/123
function getUser(id) {
  // Implementation only fetches data from a database store
  return database.query("SELECT * FROM users WHERE id = ?", [id]);
}

Defining Idempotency

Idempotency is the property where multiple identical requests yield the same result on the server as a single request. If a client performs an operation once and the server state updates, performing that same operation again with the same parameters should not cause the state to change further beyond the first successful application. This is essential for reliability in distributed systems where network instability is common. If a request is sent but the response never arrives due to a timeout, the client has no way of knowing if the action was processed. By ensuring operations are idempotent, we empower the client to safely retry the request without worrying about creating duplicate records or corrupted state. This creates a predictable contract where the cumulative effect of redundant requests is identical to the single execution.

// PUT is idempotent because the client specifies the exact final state
// PUT /users/123
function updateUserInfo(id, userData) {
  // Overwrites the record entirely, so multiple calls yield the same state
  return database.execute("UPDATE users SET name = ? WHERE id = ?", [userData.name, id]);
}

Non-Idempotent Operations

Non-idempotent methods, such as 'POST', are designed to perform actions that do not guarantee the same outcome when repeated. A classic example is creating a new resource; if a client submits a 'POST' request to add a user, repeating that request usually leads to the creation of a second, distinct user resource with a different identifier. Because these operations lack the idempotent guarantee, the server is expected to generate new state each time. This distinction is vital for client-side developers who must implement logic to avoid accidental double-submissions. If a system requires 'POST' to be safe for retries, developers often must implement server-side idempotency keys. This bridges the gap by allowing the server to recognize duplicate requests and return the original successful response instead of performing the action a second time.

// POST is NOT idempotent; multiple calls create multiple resources
// POST /users
function createUser(userData) {
  // Each call creates a new row with a unique, auto-incremented ID
  return database.execute("INSERT INTO users (name) VALUES (?)", [userData.name]);
}

Implementing Idempotency Keys

When an operation is inherently non-idempotent but needs to support safe retries, we utilize idempotency keys. An idempotency key is a unique identifier generated by the client and sent in an HTTP header, such as 'X-Idempotency-Key'. When the server receives a request with this key, it stores the key alongside the result of the initial operation. If a subsequent request arrives with the exact same key, the server checks its store, realizes the request has already been processed, and returns the cached response rather than executing the logic again. This pattern is widely used in payment processing and financial services where duplicate transactions are catastrophic. By offloading the state check to the server, you transform a risky, non-idempotent operation into a safe, predictable transaction flow that guarantees data integrity.

// Simulating a server-side idempotency check
function processPayment(paymentDetails, idempotencyKey) {
  if (cache.exists(idempotencyKey)) {
    return cache.get(idempotencyKey); // Return previous result
  }
  const result = bank.charge(paymentDetails);
  cache.set(idempotencyKey, result); // Store for future retries
  return result;
}

Selecting the Correct Method

Choosing the correct HTTP method is not merely about semantics; it is about establishing the expected behavior for the entire system architecture. You should use 'GET' only when you have no intention of altering data. 'PUT' should be used when the client wants to replace the entire resource, and it is inherently idempotent. 'DELETE' is also idempotent, as deleting a resource that is already gone results in the same state as if it were present and then deleted. 'POST' remains the catch-all for non-idempotent actions that create new resources or trigger complex side effects. By carefully selecting methods that map to these principles, you simplify debugging, improve network caching, and allow for automated retry logic that does not require custom handling for every individual endpoint in your API design.

// DELETE is idempotent; repeating it does not change the outcome
// DELETE /users/123
function deleteUser(id) {
  // Result is the same whether the user exists or was already removed
  return database.execute("DELETE FROM users WHERE id = ?", [id]);
}

Interview questions

All REST API Design interview questions →

Check yourself

Take the full REST API Design quiz →