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>
