Art of Codeartofcode
Lesson 16 of 17

24. APIs and Idempotency

1
The picture to keep in your head
2
24.1 What is an API contract?
3
24.2 What are the main API styles?
4
24.3 How do you version an API?
5
24.4 How does pagination work (offset vs cursor)?
6
24.5 How should errors and status codes work?
7
24.6 How does API auth work, in one page?
8
24.7 What is the double-charge problem?
9
24.8 How do idempotency keys work?
10
24.9 How do you retry safely?
11
24.10 How do webhooks work?
12
Memory card and where the analogy breaks
13
Practice: five levels
14
Interview questions
15
Solutions
16
Sources
17
Code lab
24. APIs and Idempotency

Sources

3 min read+10 XP

Source notes

  • HTTP method semantics (safe and idempotent methods) and status codes: IETF RFC 9110, "HTTP Semantics", 2022. Problem Details for HTTP APIs: IETF RFC 9457, 2023. Sunset header: IETF RFC 8594.
  • Stripe idempotent requests: results (status code and body, including 500 errors) saved for the first request per key and returned for later requests; keys can be removed after at least 24 hours; reusing a key with different parameters returns an error. Stripe API documentation, "Idempotent requests", checked 2026-10-08.
  • Stripe webhooks: HMAC-SHA256 signatures in the Stripe-Signature header; retries with exponential backoff for up to three days in live mode. Stripe documentation, checked 2026-10-08.
  • Idempotency-Key HTTP header: IETF HTTPAPI working group draft.
  • gRPC and Protocol Buffers: grpc.io documentation. GraphQL: graphql.org specification.
  • OAuth 2.0: IETF RFC 6749. JSON Web Tokens: IETF RFC 7519.
  • Call volumes, loss rates, page sizes and storage figures are illustrative assumptions; arithmetic computed 2026-10-08.
  • Level 3 and Level 4 code: tested 2026-10-08 (code/ch24_apis.py, all checks pass).