PHP REST API Idempotency Keys

Require clients to supply unique request keys and return a stored response for exact retries. The examples separate the essential operation from the conditions a production implementation must enforce.

What It Does

Require clients to supply unique request keys and return a stored response for exact retries.

Prerequisites

Use a dedicated development environment with test accounts and records. Separate authorization, validation and error handling from response formatting; never copy demonstration-only secrets into production.

Example 1: Core Behavior

This scenario applies the exact rule described in the guide, with controlled sample values.

<?php
$key="req_abc"; $scope="user_19";echo hash("sha256",$scope."|".$key);

Example 2: Alternative or Failure Case

This scenario applies the exact rule described in the guide, with controlled sample values.

<?php
$key="req_abc"; $requestHash=hash("sha256","payload2");$savedHash=hash("sha256","payload1");echo hash_equals($savedHash,$requestHash)?"Same":"Conflict";

Practical Example: Applying the Rule

This practical workflow performs the relevant operation, with strict error checks. Configure the required transport or database driver before running it.

<?php
$pdo = new PDO('sqlite::memory:', null, null, [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
$pdo->exec('CREATE TABLE request_replays (scope TEXT, key TEXT, fingerprint TEXT, reply TEXT, PRIMARY KEY(scope,key))');
$scope = 'account_13'; $key = 'request_48'; $fingerprint = hash('sha256', '{"amount":12}');
$pdo->beginTransaction();
try {
    $insert = $pdo->prepare('INSERT OR IGNORE INTO request_replays VALUES (?,?,?,?)');
    $insert->execute([$scope,$key,$fingerprint,'{"status":"accepted"}']);
    $row = $pdo->prepare('SELECT fingerprint,reply FROM request_replays WHERE scope=? AND key=?');
    $row->execute([$scope,$key]); $existing = $row->fetch(PDO::FETCH_ASSOC);
    if (!hash_equals($fingerprint,$existing['fingerprint'])) throw new LogicException('Conflicting replay');
    // Perform the real action inside the same transaction on first insertion.
    $pdo->commit(); echo $existing['reply'];
} catch (Throwable $e) { if ($pdo->inTransaction()) $pdo->rollBack(); throw $e; }

Important Behavior and Edge Cases

A reused key with a different payload must fail instead of replaying unrelated results.

Comparison with Related Functions or Patterns

Common Beginner Mistakes

Key Takeaways

• Require clients to supply unique request keys and return a stored response for exact retries.
• A reused key with a different payload must fail instead of replaying unrelated results.
• Database unique constraints serialize competing requests more reliably than process locks.

Select this API or pattern based on its documented behavior and the trust boundaries in your own application, and test all external integrations against their actual deployments.