generated from coulomb/repo-seed
44 lines
1.2 KiB
Markdown
44 lines
1.2 KiB
Markdown
# Pattern: Idempotent Command API
|
|
|
|
Status: seed
|
|
Readiness target: RL2 private beta
|
|
Primary owners: product repos
|
|
Genesis family: Application/API security
|
|
|
|
## Problem
|
|
|
|
Retries, duplicate submissions, and partial failures can create unsafe
|
|
state changes when command APIs are not idempotent.
|
|
|
|
## Context
|
|
|
|
Use this pattern for payment-like operations, provisioning, tenant
|
|
configuration, file processing, job submission, and external callbacks.
|
|
|
|
## Forces
|
|
|
|
- Networks and clients retry requests.
|
|
- Commands need audit and correlation.
|
|
- Duplicate execution can create data or authorization errors.
|
|
- Some commands must be scoped to actor and tenant.
|
|
|
|
## Solution
|
|
|
|
Require command identifiers and replay-safe semantics for state-changing
|
|
operations. Bind idempotency keys to actor, tenant, command type, and
|
|
resource scope.
|
|
|
|
## Verification
|
|
|
|
- Replaying a command id returns the prior result or safe status.
|
|
- Idempotency keys cannot be reused across tenants or actors.
|
|
- Command audit records include correlation id and outcome.
|
|
- Partial failures are recoverable without duplicate effects.
|
|
|
|
## Related Patterns
|
|
|
|
- Tenant Context Propagation.
|
|
- Central Audit Ledger.
|
|
- Schema-First API Security.
|
|
- Incident Runbook Library.
|