Contracts and security
Handle retries and abuse
Use request limits, idempotency, and safe timeouts to make the API predictable under duplicate traffic and deliberate pressure.
8 minute lesson
Networks retry and users double-click. Attackers also send requests faster than a normal client. The API needs explicit policies for both cases.
Cap body size and request duration, rate-limit by an appropriate identity, and return useful 429 responses. For important POST operations, an idempotency key can let the server return the original result instead of creating a duplicate.
Apply cheap limits early. Reject an oversized body before parsing it, stop work when a timeout or client cancellation is signaled, and bound database and upstream calls too. An IP address may represent many users or be supplied through an untrusted proxy header, so choose the rate-limit identity from authenticated users or verified network metadata.
Store an idempotency key with the caller identity, a fingerprint of the relevant request, processing state, and the final status, headers, and body. A unique constraint makes simultaneous duplicates converge. Reusing the key with different input must fail rather than return an unrelated result. Define retention and failure recovery so a crashed in-progress record does not block the caller forever, then test sequential and concurrent duplicates.
Design an idempotency record for book creation and a small per-identity development rate limit.
Lesson completed