5 Tips for a Game-Changing API Design Review

Matthew Reinbold

January 19, 2022

Google had an API problem. As described in their 2016 paper, “API Design Reviews at Scale,” the number of APIs produced grew tremendously over the previous decade. So too did the number of wild inconsistencies and usability problems. No single issue was the culprit. Instead, users “suffered a death from a thousand papercuts.”

To solve the issue, Google instituted a lightweight, scalable, and distributed design review process. Peer review has long been a staple of healthy, modern software development practices. Google’s application of the approach to API design ultimately reduced usability defects while being more efficient than API usability tests.

Companies of all sizes, not just the Googles of the world, can benefit from an API design review process. But what is involved?

1. Different perspectives strengthen an API design review

First and foremost, API design reviews are not code reviews. Rather, a design review is about assessing the service interface’s intuitiveness, completeness, and consistency. The conversation is about harnessing the expertise and talents of many individuals. Through that conversation, a more robust, durable, and consistent design emerges.

During this conversation, the API-producing team should have the greatest understanding of the problem. This intimacy is vital to ensure that the operation of the various subsystems and runtime expectations are properly represented.

Some additional reviewers may approach the API from the perspective of a new user, providing a fresh set of eyes similar to how new integrators would experience the API. Other reviewers may have significant accrued experience across many APIs, providing a breadth of API knowledge that pairs well with the development team’s depth.

2. An API review starts with an API description

Before we can share information, we have to speak the same language. The same goes for the business intent conveyed via a service interface. In request and response APIs, the affordances offered by an API may be captured in a description written to the OpenAPI Specification (OAS). Query APIs, like those using GraphQL, can use an SDL document. Or the means of articulation may be a Postman Collection, an open-source format capable of capturing both endpoint payloads as well as operational information. Similarly, more real-time APIs may describe their interface with an AsyncAPI description.

Regardless of the specification chosen, capturing an API’s unique operation in a standardized representation enables conversations. Consistent, machine-parsable descriptions also unlock automated tooling. Leveraging automation like linting for the important but undifferentiated syntax wrangling frees valuable time to discuss more subjective areas, like API-product fit.

Over time, this API definition becomes a living artifact, documenting the accumulation of knowledge and testing assumptions along its journey. After the design review, this artifact serves as the basis for API documentation for future customers.

3. Predefined style guides underpin a design review

Some design problems may have no obvious “right” answer. This ambiguity can lead to inconsistencies and usability problems in large API ecosystems. An API style guide provides a suggested, sometimes required, collection of solutions for those design problems.

Nearly all companies that employ an API design review will have a set of criteria they’ll review against. These API style guides should be easy to discover, understand, and implement. Furthermore, any style guide should include a defined process for how contributors can modify and evolve the contents over time.

The problems that the style guide content addresses should relate to an outcome the company seeks to drive in the API ecosystem. Outcomes may include achieving greater consistency for:

• Authentication methods
• URI and parameter naming conventions
• Error handling
• Versioning
• Payload structure and format
• Filtering
• Linking and pagination

While those areas are needed, an API design review should also seek to assess not just the API’s form but its function. Diving deeper into why an API needs to exist and how its business value could be best expressed is hard to quantify in a standards document. But applying additional effort addressing those aspects can have a considerable positive impact on the final design.

4. Execution of an API design review varies

The mechanism by which the design review is performed should vary to accommodate the existing processes and norms readily available within the organization. A review could be performed asynchronously, like exchanging comments within source control, the company CMS, or shared document. In my experience, though, what these scenarios gain in individual contributor flexibility they lack in nuance and follow-up engagement. Few people seek to have more meetings in their schedules. However, gathering the necessary stakeholders together “live” enables a higher degree of exchange. This will significantly reduce the amount of subsequent clarification and frustration for all involved.

Regardless of how the review is performed, a critical consideration must be the intended distribution scope of the API:

• Is the API an internal component known only to the immediate development team?
• Or will the API be used within the business division?
• Will the API remain within the organizational firewall but be critical infrastructure used across the entire organization?
• Or must we expand the potential users to include those in the larger world, either because they are explicit vendors or any third-party without restriction?

Your answer to those questions may significantly impact the nature of an API design review. Your organization may decide that APIs with limited exposure outside of the immediate implementation team, as in the case of microservices, may not warrant a review at all. Durable interfaces exposed to the entire world require a degree of effort on the opposite side of the spectrum.

5. Feedback should flow both ways

A healthy design review process isn’t one-way dissemination of information, flowing from reviewer to reviewee. Instead, the omissions or oversights present in an API’s first draft provide firsthand, actionable information to design reviewers. This signaling should form the basis for subsequent course correction in the company’s processes, standards, and tooling.

There are other, more formal ways to assess changing API development team preferences, appetites, and maturity. However, few are more freely available in terms of additional time or energy than applying empathetic listening during an existing conversation. Adept reviewers will listen as much as they speak, identifying patterns on what approaches are working, which aren’t, and what training needs may be emerging.

Conclusion

After Google introduced its lightweight review process, they conducted a series of interviews to assess whether it had the intended effect. They found that approximately 91% felt that the overall quality improved post-review. API producers also repeatedly suggested that their API was now more consistent with their peers, to the Google ecosystem’s greater benefit.

More consistent, holistic API design improves an API consumer’s developer experience. When done well, an API design review provides an opportunity for multiple parties, each with its expertise, to collaborate and craft a better developer experience than what any of them might have done in isolation.