Idempotent API Call Wrapper Generation Prompt

This prompt is for developers and platform engineers who need to wrap a non-idempotent API operation with idempotency guards. The job-to-be-done is generating production-ready wrapper logic—including idempotency key generation, state storage, replay detection, and conflict resolution—directly from an API specification. You should use this prompt when you have a clear API contract (OpenAPI, protobuf, or a well-documented REST endpoint) and you need to produce a safe wrapper that prevents duplicate side effects in distributed systems. The ideal user understands distributed-systems concepts like at-least-once delivery, idempotency keys, and state persistence, and needs a concrete implementation starting point rather than a theoretical explanation.

Do not use this prompt when the API operation is already idempotent by design (e.g., pure reads, upserts with unique constraints, or PUT operations with full resource replacement). It is also inappropriate when you lack a clear API specification—the prompt requires structured input to produce reliable wrapper logic. Avoid using the generated wrapper directly in production without adding persistence backends, testing partial-failure scenarios, and validating key-collision behavior. The prompt produces wrapper logic and test cases, but the storage layer, retry policy, and operational monitoring remain your responsibility.

Before running this prompt, gather the API specification, the desired idempotency key strategy (client-supplied, server-generated, or deterministic fingerprint), the state storage mechanism (Redis, DynamoDB, PostgreSQL), and the idempotency window duration. The prompt expects these as explicit inputs so it can generate wrapper code that matches your infrastructure. After generating the wrapper, run the included test cases against a real or mocked backend to verify correct behavior under concurrent requests, timeouts, and key collisions. If the API has side effects that span multiple downstream services, you will need additional orchestration logic beyond what this prompt generates.

This prompt template generates production-ready idempotency wrapper code for non-idempotent API endpoints. It takes an API specification and produces wrapper logic that prevents duplicate side effects through idempotency key management, state tracking, and replay detection. The template is designed to be adapted for different languages, frameworks, and storage backends by filling in the placeholders with your specific API contract, constraints, and output requirements.

codeCopy
You are an expert distributed-systems engineer specializing in idempotent API design. Generate a complete idempotency wrapper for the following API endpoint.

## INPUT
API Specification:
[API_SPEC]

Target Language and Framework:
[LANGUAGE_AND_FRAMEWORK]

Storage Backend for Idempotency State:
[STORAGE_BACKEND]

## CONSTRAINTS
- Idempotency key source: [KEY_SOURCE]
- Idempotency key format: [KEY_FORMAT]
- State retention period: [RETENTION_PERIOD]
- Maximum concurrent requests per key: [MAX_CONCURRENCY]
- Timeout for in-progress requests: [TIMEOUT_MS]
- Error handling strategy: [ERROR_STRATEGY]
- Required idempotency guarantee level: [GUARANTEE_LEVEL]

## OUTPUT REQUIREMENTS
Generate the following components as [OUTPUT_FORMAT]:

1. **Idempotency Key Generation Function**
   - Extract or generate a deterministic key from the request
   - Handle key collision and uniqueness guarantees
   - Include key validation logic

2. **State Storage Interface**
   - Define the storage contract (get, set, delete, lock)
   - Include TTL and cleanup mechanisms
   - Handle storage failures gracefully

3. **Request Processing Logic**
   - Check if key exists and determine state (new, in-progress, completed, failed)
   - For new keys: acquire lock, execute request, store result, release lock
   - For in-progress keys: wait or return conflict based on timeout
   - For completed keys: return cached response (replay)
   - For failed keys: apply retry policy or return error

4. **Replay Detection and Response**
   - Match incoming request fingerprint to stored request
   - Detect mismatched payloads for same idempotency key
   - Return appropriate HTTP status codes (200, 409, 422, 425)

5. **Concurrency Control**
   - Implement distributed locking for the idempotency key
   - Handle lock acquisition failures and timeouts
   - Prevent race conditions during initial request processing

6. **Error Handling and Edge Cases**
   - Partial success scenarios (request executed but response storage failed)
   - Storage unavailability during key lookup
   - Key expiration during in-progress request
   - Clock skew between distributed nodes

## TEST CASES
Include test cases for the following scenarios:
- [TEST_CASE_1]
- [TEST_CASE_2]
- [TEST_CASE_3]
- [TEST_CASE_4]
- [TEST_CASE_5]

## OUTPUT SCHEMA
Return the wrapper as [OUTPUT_SCHEMA] with clear separation between:
- Core wrapper class/module
- Storage adapter interface
- Lock provider interface
- Configuration object
- Test suite

## ADDITIONAL INSTRUCTIONS
[ADDITIONAL_INSTRUCTIONS]

To adapt this template, replace each square-bracket placeholder with concrete values from your system. The [API_SPEC] should include the endpoint method, path, request body schema, and expected response shape. For [KEY_SOURCE], specify whether the idempotency key comes from a client-provided header, a request-body hash, or a composite key. The [GUARANTEE_LEVEL] field accepts values like exactly-once, at-most-once, or at-least-once-with-deduplication and drives the strictness of the generated locking and storage logic. When filling [TEST_CASE_1] through [TEST_CASE_5], prioritize the scenarios most likely to fail in your environment: partial-success during storage write, timeout during lock acquisition, duplicate submission with different payloads, key collision under high concurrency, and replay of a previously successful response after key expiry.

The prompt generates wrapper logic, but the real work happens when you integrate that output into a live system. This harness must treat the generated code as untrusted until it passes deterministic checks. The wrapper logic typically includes idempotency-key extraction, a state store (Redis, DynamoDB, or Postgres), and a replay-detection branch. Your harness should parse the model's response into a structured object containing at minimum the wrapper_code, key_generation_logic, storage_schema, and test_cases fields. If the model fails to produce valid, parseable output, the harness must trigger a structured retry with the original API spec and the specific parse error injected into the retry prompt context.

Validation happens in layers. First, a static analysis layer checks that the generated wrapper imports only allowed libraries, does not contain network calls outside the defined API boundary, and handles the three required states: new_request, in_flight, and completed. Second, a deterministic test harness executes the generated wrapper against a local mock of the target API, injecting the test cases the model produced. You must verify that partial-success scenarios (where the API call succeeds but the state write fails) leave the system in a recoverable state, not a poisoned one. Third, a concurrency test runs multiple simultaneous requests with the same idempotency key and asserts that exactly one API call reaches the downstream service. Any violation of this invariant should block the wrapper from promotion.

Retry logic in the harness itself must be bounded. If the model produces syntactically invalid code three times, escalate to a human reviewer with the full failure log and the original API spec. Do not loop indefinitely. For key-collision scenarios, the harness should inject a simulated collision into the test suite and verify that the wrapper's conflict-resolution strategy (use-first, reject, or merge) matches the policy defined in your [CONSTRAINTS] input. Log every generated wrapper version, its validation results, and the decision (promote, retry, or reject) to an audit trail. This is critical for debugging production idempotency violations later.

Model choice matters here. Use a model with strong code-generation capabilities and a large context window to hold the full API spec, constraints, and few-shot examples. If your API spec is large, consider chunking it by endpoint and generating one wrapper per endpoint rather than one monolithic wrapper. The harness should also enforce a human approval gate before any generated wrapper touches a production API, because an idempotency bug can cause duplicate charges, double-sent emails, or corrupted state. The prompt is a starting point; the harness is what makes it safe.