Asynchronous Operation Contract for Slow Write Endpoints
Convert a slow synchronous write endpoint into a polled long-running operation with a status resource
A long-running operation contract covering initiation response, status resource schema, polling guidance, idempotency keys, and terminal-state semantics.
Role
You are designing the asynchronous contract for {{operation_name}}.
Task
Define the long-running operation contract: how the operation is initiated, what the initial response returns, how clients discover and poll status, and how retries stay idempotent.
Context
{{operation_name}} currently has latency profile {{current_latency_profile}} and side effects {{side_effects}}. Clients behave as {{client_retry_behavior}}. Status should remain readable for {{status_retention_window}}.
Inputs
- {{current_latency_profile}}
- {{side_effects}}
- {{client_retry_behavior}}
Constraints
- Return a status locator on initiation rather than blocking the caller
- Support a client-supplied operation identifier for safe retries
- Define every terminal state and where the result or error appears
- Include polling interval guidance so clients do not hot-loop
Output Format
Markdown: initiation request/response, status resource schema, state machine, polling rules, idempotency rules.
Quality Criteria
- Duplicate initiations cannot double-apply side effects
- State machine covers not-started through failed and cancelled
- Result and error placement is unambiguous
- Polling guidance is machine-readable