engineering
Cursor pagination is the right default for API list endpoints. But cursors break in subtle ways when the underlying data changes between page fetches. The patterns that handle deletions and updates correctly are worth knowing before you ship.
engineering
Webhook subscriptions almost always need filtering. The patterns that work are a small flat namespace of event types, optional resource filters per subscription, and explicit handling of new event types as they get added.
engineering
The page size limits in your API are usually set once in an early ticket and then become permanent. The decisions matter more than they look because customers build their integrations around the constraints you ship with.
engineering
Search endpoints sit between database query and product feature. The decisions that make them survive contact with real customers are not the ones most API guides emphasize.
engineering
Most APIs conflate quotas and rate limits, returning the same 429 status for both. The distinction matters because the right response from the customer is different in each case, and conflating them produces support tickets about charges that customers cannot diagnose without reading source cod
engineering
The standard webhook playbook assumes a desktop or server consumer. The receiver has a stable public URL, persistent network connectivity, and a server-side application that can be relied on to acknowledge events within a few hundred milliseconds. Mobile clients break every one of these assumptions. The phone is behind NAT
engineering
Every API that accepts non-idempotent operations eventually has the duplicate-charge incident. A customer's mobile client retries a payment because the request appeared to hang. The original request actually succeeded but the response was lost on the way back. The retry succeeds too. The customer is charged twice. The
engineering
Rate limiting from a single application instance is a solved problem; rate limiting across a fleet of instances with consistent enforcement is harder than it looks. The algorithm choice matters less than the coordination strategy, and the patterns that work treat consistency as a tunable knob r
engineering
A webhook replay button is one of the highest-trust features a webhook API can offer, and one of the easiest to design wrong. The shape that customers actually want is replay-by-event-ID, not replay-by-time-range, and the discipline that makes it safe is consumer-side idempotency that is docume
engineering
A single global rate limit lets one noisy tenant slow down everyone else. A per-tenant rate limit lets one expensive endpoint slow down everything that tenant does. The right design is a small matrix of limits at different scopes, and the wrong design is to keep adding global limits one at a ti
engineering
Auto-increment primary keys leak business information, expose enumeration attacks, and constrain migration paths. Replacing them at the API boundary with a separate public identifier is one of the schema decisions that pays off most over time. The patterns that work and the ones that don't.
engineering
Idempotency keys let clients retry safely without producing duplicate side effects. The basic mechanism is straightforward, but the production patterns — handling in-flight duplicates, response caching, key scoping, expiry — have failure modes that aren't obvious until you've debugged them.