API Governance Principles
Well-governed APIs reduce integration friction, improve developer trust and lower long-term maintenance cost. These principles apply regardless of organisation size or API surface area.
Contract-first design
Every API should begin with an OpenAPI specification reviewed by product and security stakeholders before a single line of implementation is written. The contract is the source of truth — not the code.
Versioning as a promise
Major version sunsets should come with a generous notice window. Breaking changes should ship with migration guidance, not just changelogs. Backward compatibility is a trust issue before it is a technical one.
REST for transactions, GraphQL for aggregation
Stateless, cacheable, idempotent REST for core transactional surfaces. GraphQL earns its place at BFF layers where clients need flexible payload shapes — not as a default choice.
Rate limiting is a feature, not a safeguard
Tiered rate limits, documented and communicated clearly, enforce fair usage, protect downstream systems and set expectations. They belong in your developer documentation, not just your gateway config.