Files

Paul O'Reilly 6154031cf9 api-design: add API-first methodology, DX, and contract testing

Extends api-design.md beyond its security/operations focus with three
new dimensions:

- §0 API-First Design Process — OpenAPI 3.1 as single source of truth,
  Spectral governance, dogfooding (UIs consume the public API, no
  privileged backdoors), auth-required-by-default as a design stance.
- §7 Documentation and Developer Experience — Scalar/Mintlify,
  RFC 9457 Problem Details error envelope, interactive playgrounds,
  generated SDKs (Stainless, Speakeasy, Fern), RFC 9745 deprecation
  signals and changelog UX.
- §8 Contract Testing and API Quality — schema validation in the
  test suite, Pact CDC vs provider verification, Schemathesis
  property-based fuzzing, oasdiff drift detection in CI, the API
  test pyramid.

Intro, cross-refs in §3.1/§3.3/§4.1, and Sources block reorganised
by topic. Index entry in BESTPRACTICES.md updated. PLAN file included
for traceability.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-04-25 13:42:03 +12:00

4.7 KiB

Raw Blame History

Enhance api-design.md — API-First Design, DX, and Contract Testing

Goal

Extend the existing api-design.md (security/operational focus) with three new sections covering the methodology, developer experience, and testing dimensions of building APIs. The user's framing: "API-first design" — robust testing, auth required by default, UIs using the same API as the public surface, OpenAPI/Swagger as a humans-friendly contract, and self-documenting features.

We are enhancing the existing file, not creating a new one. Same file, new sections.

Scope

New Section 0 — API-First Design Process (top of file, before Transport Security)

Design the contract before writing code
OpenAPI 3.x as the single source of truth
Style guides + Spectral linting / API governance
Design reviews
Dogfood your own API: UIs and internal tools consume the same public API surface
No privileged "internal-only" backdoors that bypass auth or expose extra fields
Auth required by default — design stance, not a bolt-on (mechanics live in §2)
Anti-patterns: code-first OpenAPI exports as an afterthought, separate "internal" and "public" APIs that drift, anonymous endpoints "because it's internal"

New Section 7 — API Documentation & Developer Experience (after Service Mesh)

OpenAPI-driven docs: Swagger UI, Redoc, Scalar, Stoplight Elements
Interactive playgrounds with example requests
Examples and error catalogs embedded in the spec
Generated SDKs (openapi-generator, Speakeasy, Fern, Stainless)
Public changelog and deprecation signals (Deprecation / Sunset headers tied to docs)
Anti-patterns: hand-written docs that drift from code, no examples, no error reference

New Section 8 — Contract Testing & API Quality

Schema validation in tests (request and response conformance)
Contract tests: provider-side (does the API match the spec?) and consumer-driven (Pact)
Property/fuzz testing the spec (Schemathesis, Dredd) to find edge cases the spec implies but the implementation breaks
Drift detection: spec-vs-implementation and spec-vs-deployed-API in CI
The API test pyramid: unit → contract → integration → smoke
Anti-patterns: tests that mock the API away, contract tests that only validate happy path, no consumer tests when SDKs are published

Light edits to existing sections

§3.1 (Versioning) — cross-ref new §7 deprecation patterns
§4.1 (Schema validation) — cross-ref new §0 (OpenAPI as source of truth) and §8 (drift detection)
Update the file overview at the top to mention all three new dimensions

Process

✅ Confirm scope with user (done)
Write PLAN.md (this file)
Dispatch 3 parallel WebSearch research agents:
- Agent A: API-first methodology, OpenAPI as source of truth, governance/Spectral, dogfooding, design reviews (2024–2025)
- Agent B: API documentation tooling — Swagger UI / Redoc / Scalar / Stoplight, SDK generation, examples-in-spec, deprecation UX
- Agent C: Contract testing — Pact, Schemathesis, Dredd, OpenAPI-driven test generation, drift detection, the test pyramid for APIs
Synthesize research into the three new sections, matching the existing Principle / Why it matters / How to implement / Anti-patterns structure
Edit api-design.md — insert Section 0 at top, Sections 7+8 after current §6, light cross-refs in existing sections, update Sources block
Update BESTPRACTICES.md index entry to include the new dimensions
Validate: file renders cleanly, internal links resolve, no duplication with existing sections
Stop. Do not commit unless user explicitly asks.

Style requirements

Match the existing file's voice: direct, opinionated, no hedge words
Each numbered subsection: Principle: → Why it matters: → How to implement: (bulleted) → Anti-patterns: (bulleted)
Cite RFCs / OWASP / vendor docs in the Sources block at the bottom of the file
Keep concrete: name actual tools (Spectral, Schemathesis, Pact, Redoc, etc.), not generic "use a linter"

Out of scope

Creating a separate api-first-design.md file
Rewriting or restructuring existing sections (1–6)
GraphQL or gRPC specifics — this file is REST/HTTP focused
A standalone tooling comparison matrix (briefly mention top tools per category, don't review them)

Open questions

Whether to add a small "API-first vs. code-first" tradeoff note in §0 — leaning yes, brief
Whether SDK generation deserves its own §7.x subsection or fits inside doc tooling — leaning own subsection

Verification

After writing, re-read the file end-to-end and check:

The three new sections fit the existing tone
No duplication with §1–6
Cross-references work in both directions
Sources block updated

4.7 KiB Raw Blame History Unescape Escape