API Design
When a webhook provider replays a year of events to recover from a multi-day outage, your receiver suddenly takes a hundred times its normal load. The patterns that handle steady-state webhooks gracefully usually buckle under replay storms. The fixes are not the obvious ones.
API Design
Long-running operations return a job ID instead of a result. Customers poll the status endpoint until the job is complete. The shape of that endpoint determines how much customer code is needed to handle the workflow correctly.
API Design
Most APIs ship with one account type: a single user, a single API key, a single billing relationship. That model breaks when customers want shared resources, multiple seats, or centralized billing. The trick is adding a hierarchy layer in a way that does not break every existing endpoint.
API Design
Customer filtering needs are usually narrower than they look. A small grammar of field-equals-value plus a handful of comparison operators handles 80-90 percent of B2B SaaS list endpoint use, while still keeping the implementation indexable and the query language documentable in a single page.
API Design
The webhook subscription dashboard exposes what events a customer can subscribe to. The right interface depends on event taxonomy, the wrong one produces support tickets. The patterns that work cover three job categories and avoid four anti-patterns.
API Design
Request timeouts are typically thought of as a client-side concern. The server-side timeout is the contract customers build retry logic against, and getting it wrong produces compounding bugs across customer integrations.
API Design
Should a comment on a post be at /comments/{id} or /posts/{post_id}/comments/{id}? Both shapes exist in production APIs for good reasons. The hybrid pattern most B2B SaaS converges on is flat canonical addresses plus scoped collection URLs for parent-context listing.
API Design
Three industry conventions for cursor pagination headers and parameters: starting_after (Stripe), cursor (Linear/GitHub-style), and page_token (Google-style). The differences are conceptual rather than mechanical and they shape what customers can do at the edges.
API Design
Export endpoints are a contract about what data the customer can take with them. The customer cases that drive the requirement are competitive migration, internal duplication, account closure, and audit. The right shape for each is different.
API Design
A nullable boolean has three states: true, false, and null. APIs that document the field as a boolean and treat null as false at some layers but as unknown at others produce bugs customers hit months after integration.
API Design
Most list endpoints include a total count by default. The cost of computing that count grows with the result set, the value to customers is usually small, and the visible-correctness expectation that it creates is hard to satisfy. The right default is no count.
API Design
Webhook subscriptions degrade silently. The customer notices when something breaks in production weeks after the integration started failing. A computed health score on each subscription surfaces degradation early without requiring customer instrumentation.