API-first design is the practice of treating the application programming interface as the primary artifact of a system, designed and contracted before the underlying implementation is written. Instead of building a service and then bolting an interface onto whatever it happens to expose, teams begin by defining the resources, request and response shapes, and behaviors that consumers will depend on, then implement a service that satisfies that agreed contract.
The reasoning is that the interface is what other people actually build against, and it is far more expensive to change after others depend on it. Microsoft’s Azure REST API guidelines make the point directly: “The URL of a service, along with its request/response bodies, establishes the overall contract that developers have with your service,” and “how you manage the overall request / response pattern should be one of the first implementation decisions you make.” Designing the contract first decouples that durable surface from the implementation behind it, which can then evolve freely as long as the contract holds.
In modern practice the contract is usually captured in a machine-readable specification, most commonly the OpenAPI Specification, which “defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code.” Writing that document first lets teams review the design, generate client libraries and server stubs, mock the API for early integration, and validate requests before any business logic exists.
The most influential organizational expression of the idea is the API mandate attributed to Amazon’s Jeff Bezos in the early 2000s, as widely recounted by former Amazon and Google engineer Steve Yegge. The mandate reportedly required that all teams expose their data and functionality only through service interfaces, that those interfaces be the only allowed form of inter-team communication, and that they be designed from the start to be externalizable. By forcing every internal capability behind a clean, network-accessible interface, the policy made Amazon’s systems composable and laid groundwork for it to later sell that infrastructure as Amazon Web Services.
API-first design and the API economy reinforce each other. When an API is the product, its contract must be stable, documented, and pleasant to consume from day one, which is exactly what designing it first encourages. Providers like Stripe, whose API is “organized around REST” with “predictable resource-oriented URLs,” reflect this discipline: the consistency a developer relies on comes from deciding the shape of the interface deliberately and early rather than discovering it as an accident of implementation.