6154031cf9
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>
82 lines
4.7 KiB
Markdown
82 lines
4.7 KiB
Markdown
# 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
|