Three unglamorous concepts. Get them wrong and you'll either get DDoSed by your own biggest customer or lose their trust the first time a network blip causes a duplicate charge.
Rate limiting caps how many requests a caller can make in a given time window. This isn't paranoia — without it, one partner's buggy retry loop can take down your API for everyone, or a customer on a cheap plan can consume the infrastructure budget of your biggest enterprise account. The product decisions here are entirely yours: what's the limit, does it vary by plan tier, what happens when someone hits it (hard block, or a 429 Too Many Requests with a Retry-After header telling them exactly when to try again), and is that limit documented clearly enough that developers can design around it instead of discovering it in production.
Pagination handles the fact that "give me all your orders" might mean returning ten records or ten million. Two common approaches:
Approach | How it works | Weakness |
|---|---|---|
Offset-based | "Give me records 100–150" | Breaks if records are added/removed mid-scroll — a customer can see duplicates or miss records entirely |
Cursor-based | "Give me the 50 records after this specific marker" | More reliable for large or changing datasets, slightly less intuitive for a developer's first attempt |
If your dataset changes frequently and callers need reliability over convenience (financial transactions, event logs), cursor-based is usually correct. This is a product tradeoff — reliability versus ease of first use — not a pure engineering preference, and you should be in that conversation.
Idempotency means calling the same request twice has the same effect as calling it once. This matters enormously for anything involving money or state changes: if a network blip causes a client to retry a "charge this card $50" request, idempotency (usually via an idempotency key the client generates and sends) is the difference between charging the customer once and charging them twice, furiously, in front of your support team. Any API you own that creates or changes something with real-world consequence needs an idempotency story, and "we haven't thought about it" is a genuine finding, not a shrug.
YOUR MOVE THIS WEEK
Find one endpoint in your API that creates something (an order, a charge, a message). Ask: "If a client's network drops right after they send this request, and they retry, what happens?" If the honest answer is "it happens twice," you've found a real gap, and probably one nobody has written down yet.