Idempotent Write Strategy: Unique Client ID vs. Server-Side State Check

When an API does not explicitly document idempotency support, the Unique Client ID (Idempotency Key) is the superior architectural choice for preventing duplicates, provided you have control over the server implementation. If you are consuming a third-party API that does not support such headers, neither strategy can be fully guaranteed without server-side cooperation.

Comparison of Strategies

Unique Client ID (Idempotency Key)

The client generates a UUID for the request and sends it in a custom header (e.g., Idempotency-Key). The server stores this key and the resulting response for a set Time-to-Live (TTL).

• Pros: Decouples identity from content; allows the same content to be posted multiple times intentionally; prevents race conditions via atomic key insertion.
• Cons: Requires server-side storage for keys and responses.

Server-Side State Check (Content Hashing)

The server hashes the request body and checks if a similar hash exists for that user within a specific timeframe before writing.

• Pros: Does not require the client to manage state or generate IDs.
• Cons: High risk of false positives (blocking legitimate identical posts); prone to race conditions unless strict database unique constraints are used on the hash.

Implementation Steps for Client-ID Strategy

1. Generate: The client creates a unique UUID for the post attempt.
2. Persist: The client saves this UUID locally alongside the pending post.
3. Transmit: Send the POST request with the UUID in the header.
4. Retry: On network timeout or 5xx error, retry the request using the exact same UUID.
5. Resolve: Once a 2xx or 4xx (client error) is received, clear the local UUID.

Verification Method

To verify the implementation, perform the following tests:

• Duplicate Key: Send two identical payloads with the same ID. The second should return the cached response of the first without creating a second record.
• Unique Key, Duplicate Content: Send two identical payloads with different IDs. The server should create two distinct records.
• Timeout Simulation: Use a proxy to drop the server's response after the write occurs. Retry with the same ID and verify no duplicate is created.

Missing Diagnostic: Do you have control over the server-side code, or are you strictly a consumer of the Stack Exchange API? If you are strictly a consumer, custom headers will be ignored, and you must rely on polling for existing content before retrying.