Design Review




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.

The End