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>
Two new topic files from research:
- api-design.md: Transport security, OAuth2/JWT/mTLS auth, API patterns
(versioning, pagination, idempotency, rate limiting), input validation,
secrets handling, zero-trust service mesh patterns. Maps to OWASP API
Security Top 10.
- llm-code-security.md: Common vulnerabilities in LLM-generated code
(injection, hardcoded secrets, hallucinated packages, over-permissive
defaults, IaC risks, crypto mistakes). Includes per-technology review
checklists and cites 18 research sources (2024-2026).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
