API Design

← Previous Chapter: Part 6: Distributed Locks, Mutex Invariants & Concurrency in Go | Series Hub: System Design Masterclass | Next Chapter: Part 8: Saga Pattern & Distributed Transactions in Go → Prerequisite: Read Part 6: Distributed Locks, Mutex Invariants & Concurrency in Go to understand distributed mutual exclusion, fencing tokens, and storage invariants before engineering exactly-once API deduplication. Answer-first: Idempotency in distributed financial APIs guarantees that duplicate network requests yield identical outcomes without adverse side effects by enforcing client-generated unique idempotency keys, atomic payload fingerprint validation, and state machine deduplication stores. Combining PostgreSQL row locking with Redis short-term TTL deduplication eliminates double-charge race conditions, ensuring sub-50ms exactly-once payment processing semantics under high concurrency. ...

Multi-Language Edition: This chapter is also available in Vietnamese at 📖 Bản tiếng Việt (Vietnamese Edition). Previous: Chapter 6 — API Gateway vs Service Mesh | Series Hub | Next: Chapter 8 — Distributed Locking: Redlock vs ZooKeeper Answer-First: In payment and financial settlement APIs, network timeouts and client retries make duplicate requests inevitable. Guaranteeing idempotency requires adhering to the IETF Idempotency-Key HTTP Specification backed by an Atomic Three-State Machine (PENDING, PROCESSING, COMPLETED). Using an atomic Redis lease lock (SET key value NX PX 30000) with SHA-256 payload tampering validation, the server ensures that a payment is executed exactly once, while duplicate retries immediately receive the cached authoritative HTTP response without re-invoking payment gateways. ...

Production AI APIs: OAuth 2.1, Gateway Rate Limiting & Prompt Versioning Answer-first: Designing production AI APIs requires OAuth 2.1 authentication with PKCE, strict semantic API versioning, token rate limiting, and standard JSON-RPC interface contracts. Running AI APIs in production for the past 18 months has produced three lessons that I did not find in any “getting started with LLMs” tutorial. They emerged from incidents, postmortems, and that specific kind of 2 AM Slack message where a word you never wanted to see — “silent,” as in “silent failure” — appears in a production context. ...