API Design

Webhooks are push notifications that depend on the receiver being available at the exact moment the event occurs, and a…

Choosing between /v1/ and a header is the easy decision. The hard part is getting clients off old versions, which…

A client that receives an error with no indication of what went wrong or what to do about it is…

When a request triggers work that takes longer than a client can reasonably wait, doing it synchronously ties up the…

URL versioning is the most visible and least subtle way to version an API, which is exactly why it is…

Limiting total requests per second protects the server and does nothing to stop one misbehaving client from consuming the entire…

GraphQL genuinely fixes over-fetching and client-driven data needs. It also brings the N+1 problem, unbounded query cost, and caching you…

When a client retries a request because it timed out, the server cannot tell whether the original request actually succeeded,…

An API that returns three different error shapes depending on which endpoint or which failure occurred forces every client to…

The limits you set on an API communicate what you expect from your clients, and getting them wrong either lets…