A client sends a POST to create a payment. The server charges the card, writes the record, and starts sending the response. Then the connection drops. The client sees a timeout and has no way to tell whether the charge happened. If it retries, the customer may pay twice. If it doesn’t, the order may never complete.

Every API that creates or changes something over a network has this problem. GET, PUT and DELETE are idempotent by definition in HTTP, so repeating them is safe. POST and PATCH aren’t. The fix most payment APIs settled on is a client-generated key sent with the request, which the server uses to recognize a retry and hand back the original answer instead of doing the work again.

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.

An API’s documentation lists the fields a record can have. It rarely tells you how many records actually have them. Those are different numbers, and on open data APIs the gap is often enormous.

The failure looks like this. You read the schema, spot a field that would make a great feature, build the feature, and then discover the field is populated on four percent of the data. By then the feature is written and the pitch has been made.

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.

A breaking change is any modification to an API that requires consumers to update their integration to continue functioning. The definition is straightforward. The practice of avoiding breaking changes while evolving an API requires engineering discipline that most teams underestimate until they have shipped a breaking change to a production API and experienced the resulting incident response.

The instinct to avoid defining something as a breaking change is strong. Removing a field that is not documented is tempting to classify as cleanup rather than a breaking change. Changing an error code from 400 to 422 for a validation failure seems like a trivial semantic correction. Adding a required field to a request body seems like a new feature rather than a breaking change. Each of these reclassifications is wrong, and each produces consumers whose integrations fail after the change.

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.

Unit tests verify that individual functions behave correctly in isolation. They run fast, catch regressions close to where they are introduced, and document expected behavior at the code level. They do not verify that the API endpoints exposed to consumers behave according to the documented contract, that changes in one service do not break the consumers that depend on it, or that the system behaves correctly under the conditions that production traffic creates.

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.