An API design proposal packages proposed API changes for review before implementation. For a RESTful API, it can include OpenAPI definition files, guide documentation, and other context needed by an API governance team. section 8.0
Treat the proposal as a reviewable pull request with automated quality gates:
- Submit the API definition, guide documentation, and supporting information in a pull request. section 8.0
- Run API linting against the definition and configure the build to fail on ERROR-level problems. section 8.7
- Compare new and old definition files for breaking changes and fail the build when incompatible changes are found. section 8.7
- Lint Markdown guide documentation according to its configured severity, then inspect warnings and other non-blocking findings during review. section 8.7
- Let the governance team review the proposal after minimum automated criteria pass; automation supports, but does not replace, design review. section 8.7
The proposal keeps API reference material distinct from guide documentation: the former is rendered from the definition, while the latter covers topics such as authentication, errors, pagination, versioning, and deprecation. section 8.0
