Offset pagination — the pattern where a consumer requests a page by specifying how many records to skip — is the default choice for most APIs because it maps naturally to SQL’s LIMIT and OFFSET clauses and allows consumers to request any page directly by number. It is also the pagination strategy that fails most visibly at scale and produces the most confusing behavior when underlying data changes between page requests.

The HTTP status code specification is 30 years old, fully documented, and widely misimplemented. The misimplementation is not ignorance — most API developers know that 200 means success and 404 means not found. It is the edge cases where the correct status code requires a moment of thought that the wrong choice gets made, and the wrong choice gets propagated to every consumer who must now handle an error that does not mean what the specification says it means.

Third-party API integrations are the debts that engineering organizations incur with optimism and repay with regret. The integration that takes two days to build and saves six months of custom development looks like an unambiguous win until the third-party API changes its pricing, introduces a breaking change, degrades in availability, or is discontinued entirely. The costs of the dependency were deferred, not eliminated. They appear later, at a time not of the integrating team’s choosing, with a magnitude that was not budgeted.

The API gateway decision — whether to build custom routing and middleware infrastructure or to adopt a commercial or open-source gateway product — is one of the more consequential infrastructure choices an API team makes, and it is frequently made at the wrong time with the wrong information.

The wrong time is too early: a team of three engineers building an API with one consumer has different infrastructure requirements than a team of thirty engineers building an API platform with hundreds of consumers. The wrong information is a product comparison done without a realistic understanding of the operational overhead that gateway products introduce regardless of their feature set.

The API specification format wars ended without a formal declaration of victory. RAML, API Blueprint, WSDL, and a half-dozen proprietary formats all had moments of advocacy and adoption. OpenAPI — originally released as Swagger by Wordnik, donated to the Linux Foundation, and renamed — outlasted them through a combination of tooling ecosystem depth, industry adoption breadth, and the practical network effects that come from being the format that most developers encounter first.

The polling versus webhooks decision is frequently made on the basis of what the API provider finds easiest to implement rather than what serves consumers best. Polling is easier to provide — it requires no additional infrastructure beyond the existing API endpoints. Webhooks require the provider to maintain delivery infrastructure, handle failures, implement retry logic, and manage consumer endpoint registration. The provider’s preference for polling is understandable. For the consumers who pay the operational cost of polling, it is not a neutral choice.

API documentation is where most APIs fail their consumers silently. The API itself may be well-designed, reliable, and feature-complete. If the documentation is incomplete, inaccurate, or organized without regard for how developers approach integration tasks, the API will generate support tickets, incorrect integrations, and the quiet abandonment of developers who find a better-documented competitor.

The documentation failures that cause the most damage are predictable: reference documentation without examples, error responses that are documented without the conditions that produce them, authentication sections that explain the mechanism but not the specific steps to obtain credentials, and code examples that work when first published and become outdated as the API evolves.

Rate limiting is one of the few API design decisions where the failure mode is existential rather than merely inconvenient. An API without rate limiting is an API that can be brought down by a single misbehaving consumer, whether that consumer is a customer with a buggy retry loop, a competitor running a data extraction operation, or an attacker attempting a denial of service. The argument for implementing rate limiting is not about fairness or monetization tiers, though it serves both. It is about operational survival.

API authentication is the area where implementation decisions have the most direct security consequences and where the choice of mechanism is most frequently driven by familiarity rather than fit. Teams that have used JWTs extensively reach for JWTs. Teams that have configured OAuth2 once and survived it reach for OAuth2. Teams that want something simple reach for API keys. Each choice reflects a different problem being solved, and using the wrong mechanism for the problem introduces either unnecessary complexity or genuine security gaps.

API versioning is the discipline that separates API providers who have operated public APIs for several years from those who have not. Early-stage API design focuses on what the API should do. Mature API design focuses on how the API will evolve without breaking the consumers who have built on top of it. The difference in focus reflects a difference in experience with the consequences of getting it wrong.

Breaking changes are changes that require consumers to modify their integration to continue functioning. They include removing endpoints, removing fields from responses, changing field names, changing data types, changing authentication requirements, and changing the semantics of existing parameters. Every team that has shipped a breaking change to a public API without a migration path has received the same feedback from affected consumers, expressed with varying degrees of professionalism.