24. APIs and Idempotency
1
The picture to keep in your head2
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 breaks13
Practice: five levels14
Interview questions15
Solutions16
Sources17
Code lab24. APIs and Idempotency
Memory card and where the analogy breaks
3 min read+10 XP
The memory card (tear this page out)
| # | Question | Memory code |
|---|---|---|
| 24.1 | API contract? | The label is a promise: same button, same result |
| 24.2 | API styles? | Coins for everyone, cards between friends, a custom order for picky screens |
| 24.3 | Versioning? | Add freely; to change a button, put in a new machine and keep the old one running |
| 24.4 | Pagination? | Don't say "skip 20"; say "after this one" |
| 24.5 | Errors and status codes? | 4xx: you fix it. 5xx: we're broken, try later. 429: slow down |
| 24.6 | API auth? | Keys for programs, tokens for people, and check every door, not just the front gate |
| 24.7 | Double charge? | A lost reply looks like a failure; retrying blindly pays twice |
| 24.8 | Idempotency keys? | Same receipt number, same result, no second charge |
| 24.9 | Safe retries? | Retry the temporary, only with a receipt, slower each time, and not forever |
| 24.10 | Webhooks? | Check it's really the bank, ignore the second SMS, and say "got it" fast |
The whole chapter in one line: Write the contract down, change it only by adding, page with cursors, say clearly whose fault an error is, and give every write a receipt number so retries and webhooks can never pay twice.
Where the analogy breaks
- A vending machine's buttons never change under you. An API's data does, between one page and the next, which is why cursors exist.
- At a machine, you can see whether water came out. Over a network, the client often can't tell whether the server acted, which is the whole double-charge problem.
- A bank SMS comes from one known number. Anyone can POST to your webhook URL, so only a signature proves who sent it.
Quick check
Five questions on this chapter. Pick an answer, then check it.
quiz