Idempotency

[Idempotent] makes an unsafe endpoint (POST/PUT/PATCH/DELETE) safe to retry: requests must carry an idempotency-key header, and the first successful response is replayed for retries with the same key and body — the handler runs once.

[Endpoint(HttpVerb.Post, "/api/booking-tokens")]
[Idempotent(DurationSeconds = 300)]                     // replay window (default 1h)
public partial class CreateBookingTokenEndpoint : Endpoint<string>
{
    public required string Purpose { get; set; }
    // ...
}

Behavior

Scenario	Result
Header missing	400 ProblemDetails (Idempotency-Key by default)
First request	Handler runs; a 2xx response is captured (status, content type, Location, body) and cached
Retry, same key + same body	Captured response replayed — handler not re-executed
Same key, different body	Treated as a distinct request (the body hash is part of the cache key)
Concurrent same-key requests	The first runs; the others get 409 while it is in flight, and replay once it lands
4xx/5xx	Not cached — the client can retry with the same key

Configuration

Per endpoint via the attribute (DurationSeconds, HeaderName), globally via PragmaticEndpointsOptions.Idempotency (HeaderName, DefaultDurationSeconds).

Requirements and notes

• Requires Pragmatic.Caching (AddPragmaticCaching()), category CacheCategories.Idempotency (falls back to the default stack). The filter fails fast when the cache is missing — silently losing the guarantee would be a correctness bug. With a distributed backend (Redis) the guarantee spans instances.
• The body hash is computed from the bound body DTO serialized with the host JSON options (endpoint filters run after binding). Form/multipart endpoints hash key + route only.
• [Idempotent] on GET/HEAD/OPTIONS warns (PRAG0513) and emits nothing — safe verbs are idempotent by definition; use [ResponseCache] for caching semantics.
• The required header is documented automatically in the manifest and OpenAPI.
• Responses are buffered for capture — keep idempotent endpoints’ payloads reasonably small.
• The endpoint runs in the caller’s own execution context, never inside a cache factory. This is what makes [Idempotent] usable together with [RequirePermission]: inside a HybridCache factory IHttpContextAccessor.HttpContext is null (dotnet/extensions#5648), so ICurrentUser sees no principal and every authenticated request is refused with 401. Sharing one execution across concurrent callers would be worse than the refusal — one caller’s response delivered to another — so duplicates are answered with 409 instead of joined.
• ⚠️ The in-flight reservation is atomic within a process. Across instances it is only as atomic as the registered ICacheStack: closing it requires a backend with a native atomic increment (Redis INCR).
• The key is mandatory where the attribute is applied: there is no honour-if-present mode, so adopting it on an existing endpoint rewrites the contract for every caller at once.