5 API design review: Checking for what you cannot automate

Imagine you’ve created a new API, and your API definition file has passed all the automated commit stage checks in your continuous integration/continuous delivery (CI/CD) pipeline. You raise a pull request (PR) to get your change merged to the main branch of your API definition project. Is there still a need to get your colleagues to review the API definition change in your PR? Yes, there is. Reviewing an API change proposal with colleagues and even prospective users enables you to get feedback that the automation can’t provide. It’s also an opportunity to review the reports from the automated checks. In this chapter, I discuss how to conduct API reviews in your APIOps workflow to get colleague feedback. People in different roles involved in designing APIs will be interested in this chapter, but API product owners or similar roles accountable for API consistency will particularly benefit from learning how to set up an effective API review process.

5.1 What is an API design review?

5.2 Running an API review meeting

5.2.1 Set up the meeting, and invite participants

5.2.2 Present the review agenda

5.2.3 Provide the business context for the review

5.2.4 Review the API resource model

5.2.5 Review the API definition

5.2.6 Note new API patterns or style guide gaps

5.2.7 Present an end-of-meeting survey

5.3 Challenges with API reviews

5.3.1 Adopting a user-centric approach

5.3.2 Poor modeling before reviews

5.3.3 Reviews occur late in the process

5.3.4 Deciding the level of review to apply

5.4 Measuring review effectiveness

5.4.1 Automated checks

5.4.2 Design review meetings

5.5 Defining your API design review process

5.5.1 Make it easily discoverable

5.5.2 Define principles and goals

5.5.3 Describe review process metrics