engineering
An SLA is a promise to customers that becomes a constraint on engineering. Getting the promise wrong is expensive in either direction: too generous and you cannot deliver, too conservative and customers do not trust the number.
engineering
Some operations take longer than a request-response cycle can hold. A status API has to tell the customer what is happening without keeping the connection open. The three patterns are polling, webhooks, and SSE, and they fit different customer profiles.
engineering
Most status pages are green almost always and green during outages. The reasons are operational and political, not technical. Here is what a trustworthy status page actually looks like and how to build one.
engineering
Most APIs treat errors as a status code plus a sentence. The APIs customers love treat errors as a recovery surface that tells them exactly what to do next.
engineering
Most APIs handle starting work well and finishing work well. The middle case (telling them to stop) is where the design tradeoffs get interesting, especially when the operation has already been partly committed.
engineering
Standard cursor pagination assumes a linear ordered list. Tree, graph, and hierarchical resources break that assumption, and the patterns that handle them well are not obvious extensions of the flat-list case.
engineering
Bulk import is the endpoint that wins or loses migration deals. A customer evaluating your API has a CSV from their old vendor and wants to know how painful it is to get into your system. The shape of the import endpoint determines the answer.
engineering
Audit logs are the kind of feature that is trivial to add badly and surprisingly hard to add well. The wrong shape produces logs that are unsearchable, untrustworthy, expensive to store, and useless when someone actually asks what happened.
engineering
Most API documentation is written for the wrong audience. Customers do not read sequentially. They scan for the four sections that answer their actual questions. The patterns that produce docs developers use and the discipline that keeps them from rotting.
engineering
A test mode that customers do not trust is worse than no test mode at all. The patterns that produce a sandbox developers actually use, and the anti-patterns that produce one they tolerate while wishing they could skip.
engineering
The default pagination response in most API design guides includes a total count. This seems obviously useful and is almost always wrong: counting is expensive, the count is stale before the client sees it, and the UX it enables is one most products do not want. The patterns that survive at sca
engineering
Error responses are the part of an API customers see when things go wrong, which means they bear disproportionate weight in determining whether customers trust the system. The patterns that survive contact with real integrations and the ones that produce angry support tickets.