API governance sets standards and review controls for API changes. Its practical test is whether shipped APIs meet those standards: a style guide alone cannot prevent inconsistent resource names, missing documentation, unsecured endpoints, or unreliable behavior. Governance must connect design decisions to delivery checks without making every change wait on a central team. section 1.0 section 1.1
Three approaches make the delivery trade-off clear:
- Let each team set its own rules. Changes can move quickly, but consumers face inconsistent APIs and teams lose opportunities to reuse patterns. section 1.7
- Publish a shared API style guide and require central design reviews. Compliance improves, but review queues and repeated feedback slow delivery; manual checks can still miss defects. section 1.7
- Automate repeatable checks in the API delivery workflow. API linting and breaking-change checks can enforce standards, while colleagues still review decisions that cannot yet be automated. section 1.0 section 1.7
A design change moving through review
Suppose a feature team changes an external API. It completes the design in the OpenAPI Specification before backend implementation, then submits it for validation. Automated checks can flag standards or breaking-change issues without waiting for a meeting. A human reviewer can still examine the resource model to confirm a shared understanding of the API. Functional tests provide a separate check that the running API behaves as its published reference says. Passing one gate does not replace the others. section 1.1 section 1.0 section 1.7
Table 5.3 An example of defining the review required for different categories of APIs
|
API category
|
API exposed externally by the organization
|
Automated API CI/CD checks
|
PR review by the internal dev team
|
PR review by the governance team
|
|---|---|---|---|---|
|
Internal API
|
No
|
Yes
|
Yes
|
No
|
|
Internal API (Externalizable)
|
Yes
|
Yes
|
Yes
|
Optional, but recommended
|
|
Private API
|
Yes
|
Yes
|
Yes
|
Yes
|
|
External API
|
Yes
|
Yes
|
Yes
|
Yes
|
Use this sample review matrix to make governance proportional to API category. Every category receives automated CI/CD checks and an internal-team pull-request review; governance-team review is absent for internal APIs, optional but recommended for externalizable internal APIs, and required for private and external APIs. Treat the categories and review rules as an example to adapt, not a universal policy. section 5.5.6
