Your OpenAPI file marks shipping_address as required on GET /orders/{id}. After Tuesday’s deploy, about one response in 300 leaves it out, because a new code path for orders created by the import job skips the field. The docs still say required. The tests still pass, since nobody wrote one for import-job orders. A client with a strict deserializer starts throwing on 0.3% of order pages, and the first report you get is “sometimes the order screen is blank”.

You inherit an integration with a partner API that has 140 endpoints, documented in alphabetical order. GET /accounts sits next to GET /adjustments, and POST /refunds is a long scroll away from the GET /charges/{id} it depends on. Nobody wrote down that a refund hangs off a charge, which hangs off an order, which may or may not have a customer. You find out the slow way: call an endpoint, copy an ID out of the response, paste it into the next call, and keep a diagram in a notebook that’s out of date by Thursday.

Take a mobile screen that lists orders: a customer name, a status, a total, a date. The endpoint behind it returns 100 KB for one page, because the vendor’s schema carries about sixty fields per order, plus nested addresses, hypermedia links and an audit trail. The phone downloads all of it over whatever connection it has, parses all of it, and keeps five fields. You can’t change the vendor’s API. You can change what reaches the phone.

Ask two developers in 2026 what platform they use to design an API, and you will get two answers that have almost nothing in common. One of them means the tool where they write the OpenAPI document, lint it, mock it and publish the reference docs. The other means the layer that sits between their application and a dozen model providers, routing requests to whichever LLM is cheapest or still up. Both groups call it “API design.” Both groups are right, because the two stacks have quietly grown into each other.

You don’t get to decide which parts of your API are the API. Your users decide that, and they decide it by accident.

We removed a field once. It was called legacy_status, it duplicated a value that already existed under a better name, and it had been marked deprecated in the docs for a year and a half. Nobody read it. We checked the logs, checked the support tickets, checked with the two biggest accounts, and shipped the removal on a Tuesday.

An SDK — a software development kit providing a client library for an API — is the interface through which most developers interact with a third-party API in production. The quality of the SDK determines the quality of the integration experience more than the quality of the underlying API, because most developers never interact with the API directly. They interact with the SDK that wraps it.

The gap between a good API and a good SDK is wide and frequently underestimated. A well-designed API with a poorly designed SDK produces frustrated developers who waste time on integration mechanics instead of building their application. A mediocre API with a well-designed SDK produces developers who build successfully and attribute the quality of their experience to the API provider rather than the SDK.

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.

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 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.

The choice between REST, GraphQL, and gRPC is treated in most discussions as a question of technical preference when it is primarily a question of context. Each protocol was designed for a specific problem space. Each performs well in that space and poorly outside it. The comparison articles that declare one winner across all use cases are either selling something or have not operated all three at production scale.

REST’s dominance in public API design is not accidental. The constraints it imposes — statelessness, uniform interface, resource-based addressing — map naturally to HTTP’s caching infrastructure, client library ecosystems, and the mental model that most developers already carry from web development. A REST API can be consumed with curl. It can be documented with OpenAPI. It can be cached at the edge. These properties have real operational value that architectural elegance alone cannot purchase.