API Design Now Means Two Different Stacks, and Both Sides Think They Own the Term

Ask a developer what platform they use to design an API and the answer depends entirely on which half of the industry they came from. One person means the tool where they write the OpenAPI document, lint it, mock it and publish the reference. The other means the routing layer sitting between their app and a dozen model providers, sending each request to whichever LLM is cheapest or still responding. Both stacks now overlap enough that spec editors, SDK generators, MCP builders and AI gateways belong in the same review, even though nobody planned it that way.

The generator layer has quietly stopped being a convenience. Comparing Speakeasy, Stainless, Fern, APIMatic and OpenAPI Generator is now a procurement exercise as much as a developer-preference one; dependency footprint and supply chain posture show up in SOC 2 audits, not just in DX surveys. Generated clients are production artifacts, and they get treated like it.

The contract you never signed

Here's the uncomfortable part: you don't decide which bits of your API are the API. Your users decide, and they do it by accident. A field marked deprecated for eighteen months, duplicated by a better-named one, absent from the logs and the support tickets, still turns out to be load-bearing for somebody on the Tuesday you remove it.

Which is really the same argument as the one about breaking changes. The definition is easy. The discipline is not, mostly because the instinct to reclassify things is so strong. Removing an undocumented field feels like cleanup. Switching a validation error from 400 to 422 feels like a correction. Adding a required request field feels like a feature. Every one of those reclassifications breaks somebody's integration, and you find out during the incident.

Internal APIs escape all of this scrutiny, and that's precisely the problem. The business case most engineering leaders skip comes down to what happens when the consumer is a colleague instead of a customer: breaking changes get coordinated over Slack, docs are optional because the author sits ten feet away, and the debt accumulates as brittle couplings to implementation details nobody meant to expose.

Choices you pay for later

Two architecture pieces sit alongside that. Event-driven versus request-response usually gets argued as Kafka against REST, which is the wrong frame; it's a decision about how services should relate, how failures spread, and how hard tracing gets when something goes wrong at 3am. And gRPC in production covers the gap between the getting-started experience and the operational one. The pitch is accurate: Protobuf serialization is faster, HTTP/2 multiplexing is real, generated stubs do kill a class of bug. The operational requirements just aren't in the pitch.

Pricing belongs in the same category of decisions that look reversible and aren't. API monetization models that work, and the ones that drive developers off is a catalogue of the familiar failures: free tiers pulled out from under people, metered pricing unpredictable enough that self-hosting won, price changes that broke the economics of apps built in good faith on top of you.

Governance, orchestration, defence

Enterprises are now trying to keep all of this from fragmenting under agentic tooling. Form.io's MCP Server and agentic coding plugin push schema governance into the build-time layer for teams working in Claude Code, Cursor and Windsurf, where five teams otherwise produce five incompatible implementations of the same thing. Orkes raised $60 million on a related bet, taking Conductor (originally Netflix's, still open source) toward AI workloads that survive the trip from prototype to production.

On the security side, Appdome rebuilt MobileBOT Defense around cryptographic identity rather than behavioural inference, on the reasonable theory that AI-generated attack tooling has made heuristics and session cookies easy to beat. App, device and session get verified before the API answers at all.

And underneath every enterprise deployment, the same wall: models that know everything in general and nothing about your business. Private domain data is what closes that gap, which is less a modelling problem than a plumbing one. Your customers' actual behaviour lives in your systems, behind your APIs, which brings the whole thing back around to whether those APIs were designed well enough to be worth querying.