# 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

1. ✅ Confirm scope with user (done)
2. Write PLAN.md (this file)
3. 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
4. Synthesize research into the three new sections, matching the existing **Principle / Why it matters / How to implement / Anti-patterns** structure
5. Edit `api-design.md` — insert Section 0 at top, Sections 7+8 after current §6, light cross-refs in existing sections, update Sources block
6. Update `BESTPRACTICES.md` index entry to include the new dimensions
7. Validate: file renders cleanly, internal links resolve, no duplication with existing sections
8. 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