The N+1 query problem is the GraphQL performance issue that every team encounters and few solve completely before it causes a production incident. Its mechanics are straightforward. Its solutions are well-documented. Its persistence in production systems reflects the gap between understanding a problem and implementing a solution that holds under all the query patterns a flexible API allows.

A GraphQL query that requests a list of posts and the author of each post produces, in a naive resolver implementation, one database query to fetch the posts and one database query per post to fetch each author. A query requesting 100 posts with their authors produces 101 database queries. A query requesting 1,000 posts produces 1,001. The number of database queries grows linearly with the number of items in the list — hence N+1, where N is the list length and 1 is the initial list query.

The OWASP API Security Top 10 is updated periodically based on analysis of real API vulnerabilities in production systems. The list is not theoretical. The vulnerabilities it documents are the ones that security researchers find in bug bounty programs, that appear in breach disclosures, and that affect applications built by teams that considered security during development. Their persistence on the list across multiple editions reflects the difficulty of eliminating them in complex systems, not a lack of awareness that they exist.

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.