API-First Design

A development methodology: design the API contract before writing any client or UI. The API is the product. Clients (web app, mobile, CLI, agent skill, third-party integrations) are equally weighted consumers. Stripe is the canonical case; the entire payments-developer experience is shaped by this discipline.

The opposite is UI-first (or client-first): build the UI, expose whatever internal API the UI happens to need, treat external API access as a secondary concern. Easier short-term; structurally limits the system later.

What "API-first" means in practice

Before any code is written:

1. The API contract is documented. Endpoints, parameters, response shapes, error codes — all specified. OpenAPI/Swagger or equivalent.
2. The contract is reviewed by API designers, security, and consumers — not just the team building it.
3. Clients are mocked first, against the documented contract, to validate the design against real use cases.
4. Versioning policy is decided before launch. Breaking changes are intentional.
5. The internal team consumes its own API. No backdoor "internal-only" methods.

Stripe famously runs an internal "API design doc" review for every new endpoint. The doc is ~20 pages. They've never deprecated a public API. The discipline shows in the developer experience — Stripe's docs are a benchmark.

Why this works

Externalisability is free. Once the API is the product, exposing it to third parties is a documentation and security problem, not an architectural rewrite.

Multiple clients are cheap. Once the API is stable and well-documented, adding a new client (mobile app, CLI, partner integration) takes weeks instead of months. Each new client is a small project.

Internal alignment. Teams negotiating an API spec early surface disagreements early. Hidden assumptions ("the front-end will just compute this") become explicit ("the API needs to return this field, computed").

Evolution is constrained. You can't subtly break the contract because it's written down and tested. Versioning becomes deliberate.

Why it costs

Slower start. Writing a spec before code feels like overhead. For a "throwaway" project it usually is overhead. For projects that grow, it's the cheapest possible insurance.

Locks in design. Once external clients depend on the API, you can't easily change it. Wrong calls cost more.

Tooling overhead. OpenAPI generation, mock servers, contract tests, version negotiation — all real work.

The trade-off: API-first wins when you're confident the system will have multiple clients (now or soon). Loses when you're sure it'll only ever be one app.

The Stripe model

Stripe's "Payments APIs: The first 10 years" and Kenneth Auchenberg's Insights from building Stripe's developer platform document the discipline explicitly:

• Internal 20-page API design doc per new public endpoint.
• Recordings of new developers integrating, watched by the API team to find friction.
• Backwards compatibility forever — no deprecations of public APIs.
• "Boring" choices: REST + JSON, no gRPC, no GraphQL on the public surface. Maximises tooling compatibility.
• Idempotency keys baked into mutating endpoints.
• Webhooks for async notifications.

The Stripe-specific tactics aren't all transferable, but the approach — treat the API as a product with its own UX — is.

API-first vs API-also vs Headless

These three terms get conflated:

• API-first is a methodology — design APIs before clients.
• API-also is "we have an API for the integrators, alongside our main UI." The UI is still privileged.
• Headless Architecture is "the system has no built-in UI; only an API." Clients are external.

API-first naturally leads to headless if applied consistently. Most modern startups claim API-first; few are truly headless.

When this applies to local tools

For local CLI tools and daemons (mxr, lazydap), "API-first" maps onto "protocol-first":

• Define the IPC protocol before any client.
• Specify the JSON schemas, the message types, the error model.
• Write a fake adapter / mock client so the protocol can be exercised in tests.
• Build the CLI client against the documented protocol, not against private daemon internals.
• Build the TUI similarly. Build the agent skill similarly.

Same discipline, different transport. The TUI is just a third-party client of the same protocol the CLI uses.

Common pitfalls

• Documenting after building. The discipline is doing it before. Documenting after is documentation, not API-first.
• Design by committee. API specs designed by 12 stakeholders end up as compromises that serve nobody. Have one author; review broadly.
• Versioning paralysis. Don't ship without a versioning plan. v1.0 should not be "we'll figure it out later."
• Internal vs external duality. If "internal" methods exist alongside "public" ones, the discipline is broken. The internal team gets the same API.

Modern signal: AI agents have made this newly important

Pre-LLM, "API-first" was a developer-experience differentiator. Post-LLM, it's table stakes. AI agents only consume APIs (via shell, MCP, REST, etc.). Tools that don't expose stable, well-documented APIs are invisible to agents. The discipline that pays off in 2026 is the same one Stripe was practising in 2014.

See Agent-Native Interfaces for the agent-era restatement.

See also

• Headless Architecture — the architectural consequence
• Client-Agnostic Cores — the synthesis
• The Bezos API Mandate — the canonical org-scale precedent
• LSP and the X-Protocol Family — protocol-first applied to dev tools
• Agent-Native Interfaces — the new dimension
• Stripe API design retrospective: https://stripe.dev/blog/payment-api-design
• Auchenberg on Stripe DX: https://kenneth.io/post/insights-from-building-stripes-developer-platform-and-api-developer-experience-part-1