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>

enhance-api-design-PLAN.md

@@ -0,0 +1,81 @@
+# 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