Blueprint: Design Review

A design review establishes a period in which an API designer or developer can submit an API for review by a formal design reviewer, as well as architects from a centralized API governance group, evaluating the API for compliance against an organizations governance design guidelines.

This Blueprint is Still in Draft Mode and Will Be Rapidly Changing!

This blueprint works to provide a high level walk-through what an API design review process can look like. API design reviews give pause before any API goes into to production to make sure every APIs meets the design standards of an organization. Designers and developers should have a wealth of resources to help them design the best possible API before it gets submitted, but the injection of the design process ensures that each API gets attention from designer reviewers, architects, and anyone else who might speak to the value an API should deliver, and the needs of consumers. APIs design processes will make your APIs better, your teams better, and your overall organization better at doing what it does best.


Define

Each API being submitted as part of an API design review process should possess the necessary artifacts and elements needed to properly evaluate the design of each API. To ensure the API design review is as efficient and effective as possible it helps to have a dedicated location for the review to happen, with everything present to to conduct review, and provide feedback around the API, as well as supporting elements. Setting the stage for a speedy but effective review, sending an API back development, or allowing it to move everything forward to production.

  • Team Workspace - Establishing and properly setting up a dedicated workspace for each API helps ensure there is always a single place to go to find everything that is happening with an API across it's entire lifecycle.
  • Team Members - Formerly defining who the team will be moving an API forward through all stages of it's lifecycle, providing a clear definition of who is responsible for each part of producing an API.
  • Github Repository - Having a dedicated Github repository for an API provides a single place where code and other artifacts can be managed, with a pipeline, issues, and other supporting elements an API will need to operate.
  • Design Rules - Machine readable rules that can be applied at design, develop, or build time to govern the design of each API, evaluating artifacts to ensure that specific design patterns are followed when crafting each API, helping make sure that APIs follow common API patterns within an industry, or as defined by the enterprise organization.
  • OpenAPI - The OpenAPI specification provides a common vocabulary for describing the surface area of request and response APIs, as well as webhooks, ensuring that API producers and consumers are on the same page when it comes to integration, but also helps stabilize multiple areas of the API lifecycle providing a contract that can be used for delivering documentation, mocks, testing, and more.
  • Reference Documentation - It is helpful for API consumers to have complete documentation for the entire surface area of an API, providing a complete reference of what is possible with an API to help consumers explore every path, parameter, schema, and other details of how an API works, making the resources and capabilities available within API something consumers can find and put to use without much work.
  • Examples - Examples of API request, responses, and messages used across API operations helps provide a versioned, evolvable, and reusable set of example and synthetic data that can make documentation richer and testing more relevant to actual business needs.
  • Mock Server - A mock server helps replicate as much of the functionality and API would have in production, before the time to actually have to write any code, making APIs be more tangible and real early on in the lifecycle, allowing teams to rapidly design an API that meets the needs of everyone involved, providing usable elements that power design, documentation, testing, and other elements of the API lifecycle.
  • Examples - Examples of API request, responses, and messages used across API operations helps provide a versioned, evolvable, and reusable set of example and synthetic data that can make documentation richer and testing more relevant to actual business needs.
  • Contract Testing - Contract tests can be derived from API artifacts like OpenAPI, JSON Schema, and GraphQL, and used to ensure there are no changes to what has been promised when an API was designed or developed, providing a repeatable test that can be run manually, on a schedule from multiple regions, or as part of a CI/CD pipeline to ensure contracts with consumers are upheld.

Process

Once ready, with all the needed artifacts and element, an API should be submitted to a well defined process for reviewing the design of an API, then providing feedback on the state of an API, and whether it is ready for production, in as short of time as possible. Reaching a desireable outcome that upholds an organization's design guidelines, and helps make teams better at what they do. Ensuring that eery API design review is a learning opportunity for both designer and reviewer. Continuing to improve the API design process with each API submitted for review, making operations incrementally better along the way.

  • Design Review - The API design review process ensures that all APIs being put into production go through a rigorous review to ensure that they comply with the standards set by organization, ensuring all APIs are as consistent as possible.
  • Design Review Timeline - Having a standardized timeline for how long API design reviews will take place, ensuring that all APIs are moved through the process as efficiently and effectively as possible.
  • Design Review Feedback - Feedback as part of an API design review is essential for each designer or developer to learn and progress in the design of an individual API, but also will evolve their skills in support of future APIs.
  • Design Review Outcomes - Every review process should have a well defined outcome, providing details on whether an API meets expectations when it comes to an organizations design guidelines, or it needs to go back for work and resubmission when ready.

This blueprint is meant to provide a standardized approach to automating API design reviews across operations as part of a standardized API lifecycle. Each element within this blueprint works to provide a simple overview of what is involved across the entire life of an API, with more detail present on the detail page for each element (if you are viewing this on the API lifecycle project site). If you are reading this via a PDF or printed version you can visit the landing page for this blueprint to access more information and view specific actions you might possibly consider taking as part of applying each element of this proposed lifecycle within your own operations. This blueprint is a living document and will continue to evolve and be added to over time based upon feedback from readers. If you have any questions, feedback, or feel like there is more information you need, feel free to jump on the Github discussion for this blueprint, or any of the individual elements present--the value this blueprint provides is actively defined by the feedback community members like you.


Discussions

YAML

Printable

Slide Deck

Return to Main Page

This provides a link back to the home page if you need it.