api
Most APIs make single-item delete safe and bulk delete an afterthought. The patterns that survive customer use require thinking about partial failure, idempotency, and the impossibility of undo.
api
Sandbox modes fail when they ship uniform mock data. Real customer integrations exercise edge cases, and sandbox data needs to surface those edges before production does.
engineering
Webhook event names are public API. Customers build switch statements and routing tables on them. The naming convention you pick on day one is the one you live with for years. There are a small number of patterns that age well and several that age badly.
engineering
A webhook subscription endpoint that accepts any URL eventually accepts URLs that point to localhost, private networks, expired domains, and the wrong customer. Validating at subscription time is much cheaper than validating during every delivery.
engineering
The HTTP Deprecation and Sunset headers let an API tell clients which endpoints are deprecated and when they will stop working. Most APIs do not use them. The reasons are mostly cultural, and the small group of APIs that do use them get most of their value from the surrounding discipline.
engineering
Every B2B API customer integrates twice: once against the sandbox to develop, once against production to ship. The quality of the sandbox is the difference between a smooth integration and a customer who never finishes. Most APIs treat sandbox as an afterthought; the ones that win developer minds...
engineering
The webhook is one of the worst customer-facing primitives in modern SaaS APIs. The customer has to operate a publicly-reachable HTTP endpoint, verify cryptographic signatures, handle retries and idempotency, decode payloads whose schema may change, and somehow tell whether a missing webhook is a sender problem or a receiver problem.
engineering
A request ID is a unique identifier the API attaches to every request. Customers paste it into support tickets, engineers grep for it in logs, and distributed tracing systems use it as the correlation key. Used well, it converts a fuzzy customer complaint into a precise debuggable record.
engineering
The Retry-After header is one of the underused communication channels between API and client. Used well, it converts a 429 or 503 from an interruption into a coordinated handoff. Used poorly or omitted, it produces retry storms that make the situation worse.
engineering
Single-request idempotency is a solved problem: the client sends a unique key, the server records the response keyed by that key, and retries return the cached response without re-executing the side effect. Bulk operations break this model in a non-obvious way. A batch of 1000 items is not a single
engineering
Changelogs are read by maybe ten percent of customers. The other ninety percent discover changes when something breaks. The patterns that close this gap are not technical; they are about which changes warrant which notification channel.
engineering
A health check endpoint that returns 200 for everything is a load balancer's favorite and an operator's worst friend. The distinction between liveness, readiness, and dependency health is what makes the difference under real production conditions.