API-First Design Methodology — Design Before You Implement

Design the contract before writing a single line of code#

API-first means the API specification is the first artifact you create — before backend code, before frontend code, before database schemas. The spec becomes the single source of truth that all teams build against simultaneously.

This is article #315 in the Codelit engineering series.

Why API-first matters#

Traditional development builds the API as a byproduct of backend implementation. Frontend teams wait. Mobile teams wait. Partner integrations wait. API-first flips this:

• Parallel development — frontend, backend, and mobile teams work simultaneously against the spec
• Better design — designing the interface first forces you to think about consumers
• Fewer integration bugs — the contract is agreed upon before anyone writes code
• Faster onboarding — new developers read the spec, not the source code
• Machine-readable contracts — generate docs, SDKs, tests, and mocks automatically

The OpenAPI contract#

OpenAPI (formerly Swagger) is the industry standard for describing REST APIs:

Anatomy of an OpenAPI spec#

openapi: 3.1.0
info:
  title: Order Service API
  version: 1.0.0
paths:
  /orders:
    post:
      operationId: createOrder
      summary: Create a new order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CreateOrderRequest:
      type: object
      required: [customerId, items]
      properties:
        customerId:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
    Order:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [pending, confirmed, shipped, delivered]
        createdAt:
          type: string
          format: date-time

Spec-first workflow#

1. Design — write the OpenAPI spec collaboratively
2. Review — all consuming teams review and approve the contract
3. Mock — generate a mock server from the spec immediately
4. Implement — backend builds to match the contract exactly
5. Validate — automated tests verify the implementation matches the spec

Mock servers#

Mock servers let frontend and mobile teams start building immediately:

Tools for mock generation#

• Prism — generates a mock server from any OpenAPI spec with dynamic response examples
• Stoplight — hosted mock servers with request validation
• WireMock — programmable mock server for complex scenarios
• MSW (Mock Service Worker) — intercepts requests in the browser for frontend testing

Effective mocking strategies#

• Static mocks — return example responses defined in the spec
• Dynamic mocks — generate realistic fake data based on schema types
• Stateful mocks — simulate CRUD operations with in-memory storage
• Error mocks — simulate failure scenarios for resilience testing

Mock server as a development contract#

When the mock server returns a response, that response shape is the contract. If the backend implementation returns something different, the backend has a bug — not the spec.

Consumer-driven contracts#

Consumer-driven contract testing ensures producers do not break consumers:

How it works#

1. Consumer writes tests — each consumer defines what it expects from the API
2. Tests generate a contract — the expectations are captured as a contract file (Pact format)
3. Producer verifies — the producer runs consumer contracts against its implementation
4. CI enforcement — contracts are verified on every pull request

Pact workflow#

• Consumer team writes Pact tests describing expected request/response pairs
• Pact Broker stores contracts centrally
• Provider team runs pact verify against their implementation
• Both sides are notified of compatibility issues before deployment

Benefits over traditional integration testing#

• No shared test environment needed — contracts are verified independently
• Fast feedback — contract tests run in seconds, not minutes
• Clear ownership — consumers define expectations, producers verify them
• Version matrix — verify compatibility across multiple consumer versions

API governance#

At scale, APIs need governance to stay consistent:

What to govern#

• Naming conventions — camelCase vs snake_case, plural vs singular resources
• Versioning strategy — URL path, header, or query parameter
• Authentication — OAuth 2.0, API keys, or JWT for different contexts
• Error format — standardized error response envelope
• Pagination — cursor-based vs offset-based, consistent parameter names
• Rate limiting — standard headers for communicating limits

Governance tooling#

• Spectral — lintable rules for OpenAPI specs, runs in CI
• Optic — tracks API changes and enforces breaking change policies
• API style guide — documented standards that Spectral enforces automatically

Automated governance in CI#

# GitHub Actions example
- name: Lint OpenAPI spec
  run: npx @stoplight/spectral-cli lint openapi.yaml --ruleset .spectral.yaml

Every pull request that modifies an API spec gets automatically validated against your style guide.

Code generation from specs#

The OpenAPI spec generates production artifacts:

What you can generate#

• Server stubs — Express, FastAPI, Spring Boot, or Go server boilerplate
• Client SDKs — TypeScript, Python, Java, Swift, Kotlin clients
• API documentation — interactive docs with try-it-out functionality
• Test scaffolding — request/response test cases from spec examples
• Type definitions — TypeScript interfaces, Python dataclasses, Go structs

Popular generators#

• openapi-generator — supports 50+ languages and frameworks
• openapi-typescript — generates TypeScript types from OpenAPI specs
• oapi-codegen — Go-specific generator with strict type safety
• Kiota — Microsoft tool for generating API clients in multiple languages

Generation workflow#

1. Modify the OpenAPI spec
2. CI generates updated types and clients
3. Generated code is committed or published as a package
4. Consuming teams update their dependency
5. Compiler catches any breaking changes immediately

API style guides#

A style guide documents your organization's API design standards:

Essential sections#

• Resource naming — plural nouns, no verbs in URLs (/orders not /getOrders)
• HTTP methods — GET for reads, POST for creates, PUT for full updates, PATCH for partial
• Status codes — 201 for created, 204 for no content, 409 for conflicts
• Request/response format — envelope structure, metadata fields, pagination format
• Versioning — when to version, how to deprecate, sunset timelines
• Security — authentication methods per API type (internal, partner, public)

Example error format standard#

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body is invalid",
    "details": [
      {
        "field": "email",
        "issue": "Must be a valid email address"
      }
    ],
    "requestId": "req-abc123"
  }
}

Living documentation#

Style guides are not static documents. Store them in version control, enforce them with linting rules, and update them through pull request reviews.

When NOT to go API-first#

API-first adds overhead. Skip it when:

• Rapid prototyping — exploring ideas is faster without formal specs
• Internal-only APIs — a single team owns both producer and consumer
• Unstable domains — the business model is still changing weekly
• Small teams — the ceremony outweighs the coordination benefits

Visualize your API architecture#

Map your API landscape — try Codelit to generate an interactive diagram showing how your services communicate through well-defined API contracts.

Key takeaways#

1. Spec first, code second — the OpenAPI contract is the source of truth
2. Mock servers unblock teams — frontend and mobile start building immediately
3. Consumer-driven contracts prevent breakage — consumers define expectations, producers verify
4. Governance keeps APIs consistent — Spectral + CI enforces your style guide automatically
5. Code generation eliminates drift — types, clients, and docs generated from one spec
6. Style guides are living documents — version-controlled, linted, and reviewed like code

This is article #315 in the Codelit engineering series. Explore all 315 articles at codelit.io/blog.