# API-First Design

A product-development approach that treats an API contract as a primary interface designed collaboratively before dependent implementations are built.

- Type: practice
- Domain: Engineering & architecture
- Level: Intermediate
- Last reviewed: 2026-09-22
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/api-first-design/>)

## What it means

API-first design starts by defining how consumers will interact with a capability before building its internal implementation. Teams model resources, operations, events, errors, authentication, and compatibility rules in a reviewable contract, often using OpenAPI for HTTP APIs. The contract becomes a shared product boundary rather than documentation produced after coding.

## Why it matters

Mobile apps, partner integrations, internal services, and automation may all depend on the same capability. Agreeing on the interface early exposes mismatched assumptions while changes are cheap. A machine-readable contract can support mock servers, generated documentation, validation, test cases, and client scaffolding, allowing consumers and providers to work in parallel.

## When to use it

Use API-first design when several teams or external consumers depend on an interface, when consistency across an API portfolio matters, or when implementation and integration must proceed concurrently. A lighter approach may be enough for a private, exploratory interface whose behavior and users are still highly uncertain.

## How it works

1. Identify API consumers, their jobs, important workflows, constraints, and service-level expectations.
2. Model the interface around stable domain concepts rather than database tables or one user interface.
3. Draft the contract with requests, responses, errors, security, examples, and compatibility expectations.
4. Review it with consumers, domain experts, security specialists, and operators; test workflows using mocks.
5. Apply automated linting and organization-wide standards without suppressing justified domain differences.
6. Implement and test against the contract, then manage versions and deprecations as product changes.

## A practical example

A payments team designs a refund API before coding it. Web, mobile, finance, and partner teams review idempotency, partial refunds, error details, and status transitions through a mock service. The provider then implements contract tests while consumers build integrations without waiting for the production endpoint.

## Where it breaks

A polished specification cannot replace user research, domain understanding, or production feedback. Prematurely freezing a contract can preserve the wrong model, while generated code may create false confidence about behavior. API-first work also requires governance, ownership, compatibility discipline, and time from consumers—not merely an OpenAPI file.

## Common mistakes

- Calling an implementation-generated specification API-first after all interface decisions are already embedded in code.
- Designing around storage schemas instead of consumer tasks and domain language.
- Specifying successful responses carefully while neglecting errors, retries, idempotency, and authorization.
- Treating the contract as finished and allowing implementation behavior to drift from it.

## Visualization

[View the visualization on the website](<https://wiki.soroush.uk/topic/api-first-design/#visualization-api-first-design>)

## Sources

1. [What Is OpenAPI?](<https://www.openapis.org/what-is-openapi>) — OpenAPI Initiative · Standards organization overview
2. [Understanding the API-First Approach to Building Products](<https://swagger.io/blog/understanding-the-api-first-approach-to-building-products/>) — SmartBear Swagger · Professional practice guide
3. [OpenAPI Specification](<https://spec.openapis.org/oas/latest.html>) — OpenAPI Initiative · Technical specification

## Related topics

- [Domain-Driven Design](<https://wiki.soroush.uk/topic/domain-driven-design/>)
- [Microservices Architecture](<https://wiki.soroush.uk/topic/microservices-architecture/>)
- [Non-Functional Requirements](<https://wiki.soroush.uk/topic/non-functional-requirements/>)
