High Level API Governance

A standardized API lifecycle can be applied to the design, development, and usage of API business workflows that are defined as machine readable collections which can be automated using monitors and CI/CD pipelines. Postman collections provide a versatile approach to defining multiple individual API requests that include authentication, parameters, headers, and other details, then organize into folders and specific sequences. Providing a format for defining, documenting, but then also executing common business workflows across many internal, partner, or external APIs. Something becomes endlessly useful when managed as part of a well defined lifecycle, equipping developers with what they need to define and design the workflows, but also maintain them, execute them, and use them to automate a variety of business tasks that exist in their worlds.

Define

API governance needs to be well defined, beginning with defining the overall API lifecycle, which this project is dedicated to doing, and the establishment of a formal strategy. Without properly defining of what governance is, and how it will be applied across the API lifecycle, it will never be realized. To establish API governance at the highest levels within an organization you need a well defined view of what is happening today across operations, and coherent articulation of where we should be going. This definition will not every e complete, but more of an ongoing journey for an organization to define itself.

API Lifecycle

This project is all about defining the base of the API lifecycle and the different entry points and priorities that exist across the API lifecycle so that we can better understand, measure, and ultimately govern how APIs move through the API lifecycle. Without governance applying to all areas of the API lifecycle, you cannot effectively govern APIs and achieve the velocity and symmetry needed to move an entire organization forward. An API lifecycle should augment and overlap with the existing software development lifecycle within an organization but work to support the specific needs of APIs, acknowledging they are central to desktop, web, mobile, and device applications and the overall IT operations and infrastructure behind everything.

Governance Strategy

API governance within any organization should have an API governance strategy, even if it begins as a simple narrative combined with a list of bullets defining the goals. An API governance strategy should provide a high level look at why and how API governance gets applied by teams, and provide a framework for leadership and teams to work together to define what API governance is, how it is applied across the API lifecycle, and what reporting and the feedback loop around success and failures should look like. The API governance strategy should be a living document that can lead API governance, but then evolves and changes based upon what is actually happening with API governance across teams and operations. The health of the API governance strategy will reflect the health of API governance across operations, and any shortcomings will only exist because of a lack of leadership and feedback with each individual team, and how it is applied across each individual API.

Organization

The structure and leadership of governance will need to be established for API governance to move forward at the highest levels, otherwise it will just be a low-level vision that a handful of teams are able to realize. The organization of governance needs to reflect the organization where it is being applied in order to have greatest impact. To do this, you have to invest resources, time, and people to helping organize, lead, and guide teams in learning about, understanding, applying, reporting, and providing feedback on what is working and what is not working when it comes to governance.

Governance Structure

The structure of API governance within an organization will determine how it operates, and what the future of it will look like. Like the overall API strategy, the governance structure should start simple, but the become a living structure that can evolve and change over time, responding to the realities on the ground floor of API operations. The structure of aPI governance across an organization will vary from organization to organization, and reflect the culture, industry, and consumers of API resources and capabilities. There are places where a top town API governance effort will work best to get things started, but there will also be places where a more bottom up approach will have the greatest impact. Where in many situations a little of both will have the greatest influence over actually how API operations works, and API operations influence the API governance strategy, structure, and leadership.

Governance Leadership

API governance leadership helps define, lead, and guide the governance of APIs across operations. Working across the organization to work with key stakeholders to understand how APIs are being developed and managed, then gathering feedback to establish what common practices are which are already in place. Working to establish an organization-wide API governance strategy that reflects what is already happening across operations, but also reflects what the future of API operations should look like. Providing leadership when it comes to the governance strategy, but also leadership when it comes to how and why it is applied across operations, ideally including a representative from each team as part of leadership, but also reflecting the architectural and business objectives of leadership.

Rules

API governance rules codifies what API governance is as it is applied as part of the design, development and build process on the ground floor of API operations. Rules provide the benchmark for what governance is across teams, and provide an artifact that can be applied across the API lifecycle by individual designers and developers, and eventually baked into the pipelines that move API infrastructure forward. Rules should reflect what is happening on the ground today, but apply enforcement as part of a forward motion, acknowledging that legacy APIs may not always rise to the level governance an organization is moving towards.

Design Rules

Design rules provide modular, codified artifacts that can be used to lint API artifacts like OpenAPI, AsyncAPI, and JSON Schema. Defining rules that represent practices that we want to see repeated across the design of our APIs, manually applied by developers at design and develop time, but also allowing them rules to be automated and run on a schedule or at build time via pipelines. Helping establish formal definitions for what API design practices should look like, educating designers and developers along the way, and also being able to actively enforce these rules going into production.

Documentation Rules

As part of wider governance it makes sense that all APIs should be documented, but it helps to have well defined guidance and rules that helps make sure it isn’t forgotten along the way. Documentation rules can help remind developers that they need documentation, as well as provide clear direction for what tools they should be use, and what process is involved with delivering up to date and accurate documentation. Depending on the process, these documentation rules can be automated, providing checks along the way that make sure documentation has been published, and even provide tests to ensure that it is up to date and matches the technical details of an API, and has all the necessary details.

Management Rules

API governance always begins with API design, but then should be also applied to API management practices as soon as possible. Governance at the API management layer involves the defining and consistently applying of policies at the API management layer, ensuring that all APIs leverage consistent usage plans, logging, and other common aspects of aPI management. Depending on the gateway and API management layer in place, policies can be defined and applied manually or automatically via management APIs or CI/CD pipelines. API management rules can be defined as JSON schema or other machine readable format and applied to the common outputs from API management infrastructure. Helping ensure that API management is consistently applied across all APIs being deployed into production, helping ensure developers are consistent in how they manage the APIs they are delivering.

Testing Rules

Testing rules are about established well define guidance for what testing should exist as part of the lifecycle for each API, as well as how these rules can applied and evaluated as part of a wider API governance strategy. Consistent testing across all APIs is essential to realizing quality at scale across an organization, and testing rules provide the foundation for how you guide developers in making sensible testing decisions as they develop and sustain their APIs, as well as automate the reporting on which APIs are in compliance with organization wide testing, and which are note.

Reporting

Reporting on the realities and outcomes of API governance across the API lifecycle is needed to make it more visual and tangible for everyone involved. Reporting across governance being applied to individual APIs, groups of APIs, and overall operations can be realized as part of native platform reporting, customized, localized or in aggregate with Postman Visualizer, or made seamless with existing operations by piping data into APM and other systems to make available for reporting and visualizations via dashboards.

Reports

Reports provide teams with visibility into the usage of individual APIs, but also the operations around them, helping us see activity, history, and the presence, or lack of presences of essential elements of the API lifecycle like documentation, testing, and other building blocks. The Postman platform provides native reporting on teams, APIs, and the activity that exists across workspaces. While also embracing an integration strategy that allows for the piping of data into other APM and observability solutions organizations are already using, providing another dimension for the creation of reports, and making them available via existing dashboards. Using API reporting to make APIs and API operations more visible in real time, allowing teams to stay aware of what is happening and be response to events that matter to an organization.

Visualizer

Postman provides a visualizer tab for each request defined as part of a collection. The visualizer tab is rendered using test scripts for each request, taking the response, applying some JavaSCript, then rendering the results to the tab for viewing alongside JSON responses or test results, providing another way to “see” the response of each API. This is something you can apply to not just the individual response of an API, but also the aggregate responses across many API requests, or even the test results of an API, or the governance of the design and operation of an API. Providing for a very powerful way to visualize the resources and capabilities provided by each API, but also the infrastructure behind the APIs, helping make API operations more visible to developers and other business stakeholders.

Conclusion

This blueprint looks at how you can approach API governance as an organization, establishing high level strategy and practices that can be used to direct governance efforts across teams. 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.