An API design can pass automated checks and still be difficult for consumers to use. A review process gives colleagues and potential users a way to assess the proposed operations, resource model, documentation, and business purpose before the design is implemented. Automation handles repeatable standards checks; people concentrate on decisions it cannot reliably judge. section 5.0 section 5.1 section 5.5.2
Start a design-stage review when an API definition change is submitted as a pull request (PR), after linting and breaking-change checks have run. Reviewers examine the change and its check reports, leave comments, and approve the PR when concerns are resolved. A small change that closely follows the style guide may need only asynchronous comments. A broad or complex change may need a meeting to establish context and resolve design decisions together. section 5.1 section 5.2.5
For a review meeting, use a repeatable sequence:
- Invite the relevant participants, present an agenda, and establish the business context and the job API consumers need to perform. section 5.2 section 5.2.5
- Examine the resource model and rendered API documentation. Check whether the design has the required operations and resources, whether any operations are missing, and whether the API boundary makes sense. section 5.2 section 5.2.5
- Inspect automated reports for warnings needing attention, then discuss design concerns not covered by those checks and capture feedback on the PR. Note style-guide gaps or recurring problems that could become automated checks. section 5.1 section 5.2 section 5.2.5
- Close by asking participants for a short survey; use the responses to assess the meeting rather than assuming that approval alone means the review was effective. section 5.2 section 5.7
Document who requests and facilitates reviews, how work is prioritized, and which changes require a meeting. Keep the process easy to find alongside the guidance teams use. Set goals for quality, speed, dependable scheduling, flexibility across small and large changes, and cost. These are choices to make for the organization, not universal rules. Human meetings consume reviewer capacity: one suggested policy reserves them for public, partner, or potentially external APIs, while allowing internal-only teams to opt in. section 5.5 section 5.5.1 section 5.5.10 section 5.5.2
Different ways to route a design
At Slack, a team shares an API definition with a cross-functional review channel; changes needing deeper discussion move to scheduled API office hours, and selected partners later review the design. Kubernetes instead defines mandatory and voluntary review categories, checks proposal prerequisites, and triages accepted requests on a board that shows status and reviewer load. Both make the path to feedback explicit without requiring every change to follow the same meeting format. section 5.6.3 section 5.6.4
Do not wait for a PR to be the first design conversation. Early guidance on the style guide, linters, API modeling, and service design can prevent problems that a late review would otherwise discover. Keep the review consumer-focused: start with what an API user sees, then work backward toward internal interfaces. section 5.3.3 section 5.7
