中文
devexamples
← Workflows

阅读中文版本

Contract-First API Design Workflow

Write the OpenAPI or protobuf contract first, review it with consumers, generate stubs and docs from it, and treat the contract as the source of truth.

intermediate~120 minapidesignci

Objective

Design an API contract before implementation so consumers and providers agree on shape and behavior early.

Environment

  • An OpenAPI or protobuf toolchain
  • A review channel including consumer representatives

Steps

1. Write the contract with request, response,

Write the contract with request, response, errors, and examples.

Expected state: The interface is specified independently of code.

2. Review it with consumers and iterate

Review it with consumers and iterate before implementing.

Expected state: Disagreements surface before code exists.

3. Generate stubs, clients, and docs

Generate stubs, clients, and docs from the contract.

Expected state: Implementations and docs cannot drift.

4. Add a breaking-change check

Add a breaking-change check on the contract in CI.

Expected state: Unintended breaks are caught.

Decision points

Spec-first or code-first?

  • Spec-first
  • Code-first with generated spec

Spec-first when many consumers integrate externally; code-first suits internal prototypes.

How strict on breaking changes?

  • Block all
  • Allow with review

Block removals and renumbering; allow additive changes without ceremony.

Expected outcome

An agreed, machine-readable contract that generates clients, server stubs, and documentation, enforced by CI.

Verification

Confirm the contract lints without errors, generated stubs compile, and the breaking-change check runs on every change to the contract.

Cleanup

Publish the contract version and record the review decisions.

Overview

Design an API contract before implementation so consumers and providers agree on shape and behavior early. Confirm the contract lints without errors, generated stubs compile, and the breaking-change check runs on every change to the contract.

Steps

  1. Write the contract with request, response, errors, and examples. Expected state: The interface is specified independently of code.
  2. Review it with consumers and iterate before implementing. Expected state: Disagreements surface before code exists.
  3. Generate stubs, clients, and docs from the contract. Expected state: Implementations and docs cannot drift.
  4. Add a breaking-change check on the contract in CI. Expected state: Unintended breaks are caught.
openapi: 3.1.0
info: { title: Orders API, version: 1.3.0 }
paths:
  /orders:
    post:
      responses:
        "201": { description: Created }
        "422": { description: Validation failed }

Verification

  • An agreed, machine-readable contract that generates clients, server stubs, and documentation, enforced by CI.

Decision points

  • Spec-first or code-first? Options: Spec-first; Code-first with generated spec. Recommended: Spec-first when many consumers integrate externally; code-first suits internal prototypes.
  • How strict on breaking changes? Options: Block all; Allow with review. Recommended: Block removals and renumbering; allow additive changes without ceremony.