Idempotency

Implementing idempotency ensures that repeated API requests have the same effect as a single request, even if they are retried due to network issues or client-side retries. In the context of a payment service API, this is crucial to prevent duplicate charges or unintended side effects.

How to Implement?

Use an Idempotency Key

• Clients generate a unique identifier (idempotency_key) for each request.

• This key is sent along with the API request (e.g., in headers or body).

• The server uses this key to track whether the request has already been processed.

• Generate a UUID or similar unique identifier for each client-initiated request.

Store and Check Request State

• Maintain a record of processed requests with their corresponding idempotency_key.

• When a request is received:

  • If the key exists, return the previously recorded response.

  • If the key does not exist, process the request and store the result.

  • If a duplicate key is used with different request data, return an error.

Handle Race Conditions

• Use database locks or atomic operations to ensure multiple simultaneous requests with the same key are handled correctly.

Set Expiry for Idempotency Keys

• Keep records of processed requests for a limited time (e.g., 24-48 hours) to avoid indefinitely storing data.

Use Proper Status Codes

• 201 Created: For new requests processed successfully.

• 200 OK: For duplicate requests returning the cached result.

Example Case: Payment Service API

Request Structure

The client sends a POST request to initiate a payment.

API Endpoint: POST /payments

Request Body:

{
  "idempotency_key": "123e4567-e89b-12d3-a456-426614174000",
  "amount": 100.00,
  "currency": "USD",
  "payment_method": "credit_card",
  "customer_id": "98765"
}

Server-Side Implementation

Pseudocode:

func CreatePayment(w http.ResponseWriter, r *http.Request) {
    var req PaymentRequest
    json.NewDecoder(r.Body).Decode(&req)

    // Check if idempotency key already exists in the database
    existingPayment, found := GetPaymentByIdempotencyKey(req.IdempotencyKey)
    if found {
        // Return the previous response if the request was already processed
        w.WriteHeader(http.StatusOK)
        json.NewEncoder(w).Encode(existingPayment)
        return
    }

    // Process the payment
    payment := ProcessPayment(req)

    // Store the result in the database
    SavePaymentWithIdempotencyKey(req.IdempotencyKey, payment)

    // Return the result
    w.WriteHeader(http.StatusCreated)
    json.NewEncoder(w).Encode(payment)
}

Latency Impact

The impact of checking or enforcing an idempotency key in the database depends on several factors, such as the database system, indexing, schema design, and the overall load on the database.

Checking an Idempotency Key

When a client sends a request with an idempotency_key, the server typically queries the database to check if the key exists.

Example Query

SELECT * FROM payments WHERE idempotency_key = 'some-unique-key';

Latency Impact

• If the idempotency_key field is indexed (e.g., UNIQUE constraint or primary key), the lookup is fast (O(log N) for B-tree indexes).

• Without an index, the database would need to perform a full table scan, leading to slower performance (O(N)).

• Under heavy load, database query times may increase, especially if the database is not optimized or lacks horizontal scalability.

Using UNIQUE Constraint

If a duplicate key is inserted, the database will reject the new record and throw an error. This is handled efficiently by most relational databases as the check is part of the insertion operation (atomic).

The database performs an index lookup before insertion:

• If the key already exists, the insert operation fails immediately.

• If the key does not exist, the record is inserted.

Latency Impact

• The impact is minimal as the UNIQUE constraint relies on an index.

• Modern databases like PostgreSQL or MySQL can handle millions of rows with minimal latency increase when a UNIQUE index is properly configured.

Typical Latency Overheads

• Index Lookup: Usually in the range of a few milliseconds (1–5 ms) for well-indexed tables with moderate size (millions of rows).

• Insert with UNIQUE Constraint: Adds a negligible amount of overhead (~1–2 ms) compared to a non-unique insert.

Operation	Latency Estimate
Query to check idempotency key	1–5 ms
Insert with UNIQUE constraint check	1–3 ms

If latency is a critical concern in your API, caching idempotency keys in a fast in-memory store (like Redis) is highly recommended.

Caching Idempotency Keys

Implementing caching idempotency in Redis is an efficient way to reduce database load and improve API latency while maintaining the benefits of idempotency. Redis, being an in-memory store, offers high-speed operations ideal for this purpose.

Implementation

Store Idempotency Keys in Redis

• When a client sends a request with an idempotency_key:

• Check if the key exists in Redis.

  • If it exists:

    • Return the cached result.

  • If it doesn’t exist:

    • Process the request.

    • Save the idempotency_key and result in Redis with an expiration time.

Set Expiration Time

• Use a TTL (Time-to-Live) to limit how long the key is stored in Redis. A typical TTL might be 24–48 hours, depending on the business logic.

• This ensures Redis doesn’t retain stale keys indefinitely, optimizing memory usage.

Handling Edge Cases

Expired Idempotency Keys

• If a client retries after the key has expired in Redis:

  • Check the database for existing processed payments as a fallback.

  • If no record exists, treat it as a new request.

Redis Downtime

• Implement a fallback mechanism to query the database if Redis is unavailable.

• Use a [[circuit_breaker]] pattern to gracefully handle outages.

Concurrent Requests

• Redis supports atomic operations like SETNX (Set if Not Exists), which prevents race conditions.

• Example:

  SETNX idempotency:<idempotency_key> <response_payload>

Conclusion

Caching idempotency keys in Redis significantly reduces database latency and improves the responsiveness of your API. By combining TTLs, atomic operations, and fallback mechanisms, this approach provides both reliability and performance for high-traffic systems.