#api design

The design detail that surprises people: Stripe caches the result of the first request under a key even when that result was a 500, and replays the failure to every retry. That is correct, and once you see why, the rest of the design follows, including where most homegrown implementations go wrong.

Everyone compares token bucket to sliding window and stops there. The decisions that actually determine whether a rate limiter works are what you key it on, whether your Retry-After header is quietly scheduling a thundering herd, and whether a client that gets a 429 can safely retry at all.

Two things would prevent most OAuth bugs. OAuth answers what a caller may access, not who they are, so using it to log people in is a category error. And the flow chart everyone agonised over has collapsed: authorization code plus PKCE, for every client type, no exceptions.

JWTs are the default choice for new apps and usually the wrong one. The reason is revocation: there is no row to delete. And the standard fix, a server-side denylist, reintroduces the database lookup that was the entire point of going stateless.

Most REST vs GraphQL vs gRPC posts list features in a table and stop. The real decision isn't about features. It's about who consumes your API and what hurts at scale.