I was recently asked how to conduct an API design review, as part of an overall engagement to establish API consistency across an organisation’s product portfolio. While every organisation’s priorities may differ, there are some key takeaways that I will share in this article. My goal is to offer insights that will provide a starting point for developing your own API design review process.
Why API design reviews?
API design reviews offer an organisation a chance to:
1. Share knowledge of upcoming APIs
2. Incorporate design feedback before coding begins
3. Become an advocate for the many developers that will use your API once it is released
4. Offer a more consistent developer experience through consistently-designed APIs
5. Catch missing or incorrect assumptions before code changes become more expensive or time is limited
If you are currently conducting API design reviews, then this article may give you some ideas for improving or expanding the process. If you are not currently conducting API design reviews, this article should provide insights on what you may wish to include. When in doubt, start simply and expand over time.
A word of caution before you proceed
Design reviews can go two ways: constructive or destructive. A constructive design review provides an opportunity to coach those newer to API design and build up and edify the entire organisation. Destructive design reviews are the opposite, typically sowing the seeds of frustration and mistrust. Worst case, design reviews will be a cause for team attrition as caustic team members invade an otherwise healthy and useful process.
Therefore, you must use caution when you conduct an API design review. Seek to ask questions first. Too often we can place our own biases and assumptions into our design review. Instead, seek to first understand by asking questions and listening. Don’t claim to know everything about API design – none of us do. Never accuse someone of deliberately designing a poor API – no one sets out to do so. Assume good intentions, listen carefully, seek to understand, then provide some recommended next steps for design improvement.
Remember: We all started out as newbies once. Model the proper reviewer behaviour that encourages improvement. Don’t try to show off how much you know about API design.
Start with the documentation
API design reviews are not code reviews. As mentioned above, reviewers are acting as an advocate for the developers that will consume your API. Therefore, we need to start with documentation.
“Documentation is the third user interface for APIs, and the most important.” – [Keith Casey]
10 Questions Your API Documentation Must Answer
If you don’t have a standard recommendation for documenting your API, start with a specification format such as OpenAPI Specification (aka Swagger) or API Blueprint. If this style of API documentation is unfamiliar, take the time to learn it as it will provide a machine-readable format for generating developer documentation. These formats are also used to drive pipeline automation and code generation.
Focus on the ‘why’ of the API
APIs exist for a variety of reasons, including: data access, customer automation, system-to-system integration, marketplace creation, and workforce automation. An API’s introduction should be clear about the following:
1. What does the API do? What capabilities does it offer?
2. What kind of authorization is required to use the API?
3. Are there related APIs that are often used in conjunction with this API?
Great introductory documentation assumes that the reader has no idea about any of your internal systems or implementation choices. They just want to get something done and they want to find out if your API will help them achieve their goals.
Expand understanding with examples
Examples of API usage are often the most important, yet missing, element of an API’s documentation. These examples do not need to be in a specific programming language (although that helps when trying to offer an API to a broad audience). Simple HTTP request/response examples, perhaps complemented with Postman collections, will go a long way.
The format of these examples may vary. You may want to offer a Readme-style approach to the examples, showing progressively more complex scenarios as a starting point for starting to use an API. They may be complete tutorials that walk the developer through the process. Or, they could just be examples offered in the introductory or operation-level documentation. We covered this topic in an article titled “Great API Documentation Requires Code Examples”.
Check for consistency
One of the common challenges for many mid-to-large size organisations is API design consistency. It is easy to spot APIs that were independently designed by teams without any cross-org consistency applied. Commonly, this is associated with organisations that lack a design review process. Even with a review process in place, inconsistencies may creep in from time-to-time.
Ensure that you have a [style guide w/ naming patterns and other key design decisions] captured. (View style guide). This will provide the necessary checklist that will help design reviews produce consistent API designs – even when APIs are designed by different teams.
Look for designs that apply common design patterns, e.g. pagination, singleton resources, etc. Not all APIs are CRUD APIs, so be consistent across all of your endpoints when the CRUD pattern needs to be expanded or deviated upon.
Review architecture and automated test coverage
While an API design review does focus on the design, you may also wish to include an architectural and test coverage review. If you conduct the review early in the process, there may not be any specific code or test coverage in place – that’s fine. The goal should be to review test plans, implementation designs, and other details that may surface missing or incorrect design assumptions.
Give it a try using a mocking tool
While reviewing documentation and design style is important, nothing provides a better developer perspective of your API design than interacting with it. If you subscribe to the API design first approach, then the team producing the API will not have produced much, if any, code yet.
Mocking tools are a great way to fill the gap and catch bad design decisions, or missing endpoints, sooner rather than later in the delivery process. These tools will often accept a definition in OpenAPI or Blueprint format to produce a mock version of your API design. Most will even store submitted data to mimic the typical CRUD pattern using an in-memory database. This will allow the producing team and reviews to try out the API to try and solve a use case. While the mock API won’t be fully-formed, it will provide a basic understanding of how the API will be used once completed.
Below is a (non-exhaustive) list of mocking tools that you may wish to explore:
– MockBin
– PostBin
– httpbin
– Postman
– Json-Server
– Mockoon
– Beeceptor
Verify the contract has been met
As the API design transitions into implementation, differences between what was documented and how the API was implemented may arise. You may wish to verify that the API does what it promises in the documentation. Tools such as Dredd are useful for comparing the actual API implementation to the initial design captured in OpenAPI or Blueprint. While not specifically part of a formal API review, it may be an additional checkpoint prior to release, or conducted as part of a secondary review later in the delivery process.
Final thoughts
It is important to accept that APIs already supported in production won’t be able to meet all of your standards. This is part of maturing your API design process and is expected. Seek to improve your API designs as much as possible, but know that there will always be inconsistencies and missed opportunities as you learn more about API design. Implementing an API design review process will help to capture your lessons learned into a repeatable process, guiding you toward a more consistent design and a better developer experience.
For information going beyond design decisions to create great style guides, you can read more on How to create an API style guide, and why.
