Idempotency in REST APIs

// Client sends a unique key per logical attempt; retries reuse the same key.
// curl example:
//   curl -X POST https://api.example.com/v1/charges \
//     -H 'Idempotency-Key: 7a9c3f12-b4e8-4e0a-9f77-0b3a8c2d1e55' \
//     -H 'Content-Type: application/json' \
//     -d '{"amount": 5000, "currency": "USD"}'

@RestController
@RequestMapping("/v1/charges")
class ChargeController {

    private final ChargeService service;
    private final IdempotencyStore store;   // Redis or Postgres

    @PostMapping
    ResponseEntity<ChargeDto> create(
            @RequestHeader("Idempotency-Key") @NotBlank String idemKey,
            @RequestBody @Valid CreateChargeRequest req) {

        // 1) Look up the key; hash the request body to detect reuse-with-different-body
        String bodyHash = sha256(req);
        Optional<IdempotentRecord> existing = store.find(idemKey);

        if (existing.isPresent()) {
            IdempotentRecord rec = existing.get();
            // Same key + same body -> replay the stored response exactly
            if (rec.requestHash().equals(bodyHash)) {
                return ResponseEntity.status(rec.status())
                    .header("Idempotent-Replayed", "true")
                    .body(rec.response(ChargeDto.class));
            }
            // Same key + different body -> 409; this is a client bug we want to surface
            throw new IdempotencyMismatchException(idemKey);
        }

        // 2) First request for this key — reserve a slot atomically (ms TTL until response known)
        if (!store.tryReserve(idemKey, bodyHash, Duration.ofSeconds(30))) {
            // Another in-flight request has the same key; 409 while it resolves
            throw new IdempotencyInFlightException(idemKey);
        }

        // 3) Execute the real work
        try {
            ChargeDto result = service.createCharge(req);
            store.commit(idemKey, bodyHash, 201, result, Duration.ofHours(24));
            return ResponseEntity.status(HttpStatus.CREATED)
                .header(HttpHeaders.LOCATION, "/v1/charges/" + result.id())
                .body(result);
        } catch (Exception ex) {
            store.fail(idemKey, ex);      // release the reservation so retries can succeed
            throw ex;
        }
    }
}

// Redis-backed store sketch (atomic reservation via SET NX)
interface IdempotencyStore {
    Optional<IdempotentRecord> find(String key);
    boolean tryReserve(String key, String hash, Duration ttl);
    void commit(String key, String hash, int status, Object body, Duration ttl);
    void fail(String key, Throwable cause);
}

record IdempotentRecord(String requestHash, int status, String bodyJson, Instant at) {
    <T> T response(Class<T> type) {
        return JSON.readValue(bodyJson, type);
    }
}