Migration windows, rollback and retry semantics
What This Concept Is
A compatibility migration is a period when multiple versions interact under explicit rules. Retry behavior is part of that contract: changing the handling of repeated requests can break consumers even when request and response shapes remain identical.
Why It Matters Here
Semester 06's outbox demonstrated atomic intent and duplicate-effect protection. This module adds the consumer-facing promise: identity scope, request fingerprint, concurrent retries, retention/expiry and what callers see after a lost response. A header name alone does not provide these guarantees.
Concrete Example
A create-reservation request commits, but its reply is lost. The client repeats the same identity and payload. The documented policy might return the original result. Reusing the same identity with a different quantity must have a declared outcome, such as a conflict, rather than silently using either value. Two concurrent retries must not both create independent reservations.
Now upgrade the server to accept a new optional request field. An old server restored during rollback may reject that field from upgraded clients. A successful old-client/new-server test does not prove rollback readiness. Either retain a compatible rollback version, keep the new feature disabled during the window, or introduce a documented negotiation/version strategy and test it.
Common Confusion / Misconception
HTTP idempotency concerns the intended server effect of repeated identical requests; it does not require identical status codes or forbid incidental logging. A custom retry key on a mutating endpoint needs application semantics and durable handling. After key expiry, a replay may create a new effect unless another mechanism prevents it; do not advertise indefinite deduplication with a finite record lifetime.
How To Use It
Keep a migration ledger: consumer versions, capability used, first/last observed use, owner, removal condition and rollback target. Telemetry with no observed old client is not proof that offline clients no longer exist. In the original HTTP lab, inject response loss after commit, race duplicate requests, restart the service and exercise the expiry boundary. Preserve the real transport and persistence evidence.
Check Yourself
Does DELETE being idempotent mean every response is identical? What must a request fingerprint include? What does a new client send after rollback? Which evidence supports removal of an old contract, and which blind spots remain?
Mini Drill or Application
Run old and new consumers against both providers wherever support is promised. Break one semantic default while leaving the schema unchanged; make a consumer test catch it. Execute rollback, a concurrent retry and a retry after expiry. Record known limits and repair the documentation-only consumer review without coaching around ambiguities.
Read This Only If Stuck
API Design Patterns — retries, versioning and deprecation. RFC 9110 section 9.2.2 defines HTTP idempotency. The exercise's application retry-key policy must be specified separately.