Once an API has consumers, breaking changes scale super-linearly. Governance is compatibility over time—not how glossy today’s PDF is. Maintain a major-version strategy, a durable deprecation channel, and contract tests against critical consumers; assess every field removal or semantic shift against a compatibility matrix.
Keep versioning predictable: major versions at hard boundaries in URL or header; minors for backward-compatible extensions. Experimental endpoints and feature headers belong behind explicit gateway isolation so experiments do not pollute stable traffic. OpenAPI or GraphQL schemas—and event schemas—belong in CI with breaking-change detectors.
Deprecation needs timelines, migration guides, and named contacts. Announcements belong in searchable changelogs and optionally response headers or a developer portal—not only chat. Critical consumers deserve parallel operation windows and comparison tooling. Emergency security deprecations can accelerate but still warrant written rationale and blast-radius notes.
Rate limits, quotas, and circuit breakers should match user-visible consequences. Returning 429 without retry guidance invites retry storms. Document exponential backoff, batch alternatives, and idempotency key usage. Personal data in responses needs field-level authorisation and audit—not “nobody would call this” optimism.
Governance is organisational: who may publish endpoints, who signs deprecations, and who funds consumer notifications belongs in a RACI. Tools encode agreed rules; they cannot invent policy.
