Blueprint: High Level API Governance

A blueprint for approach the governance of APIs from the top down, establishing a higher level strategy for defining what governance is, and then helping spread guidance across teams that helps enable them to deliver more consistent APIs across a more consistent API lifecycle no matter what type of API they are delivering.

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

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 - It is impossible to govern an API lifecycle that is not defined. It takes a clear and articulate definition of how the API lifecycle is put into motion across teams to reach a point where you can measure, guide, enforce, and evolve how APIs move across a well-defined API lifecycle in any consistent way. -
  • Governance Strategy - Having a well defined and clearly articulated strategy for what the governance of APIs across an organization looks like is important for helping teams find alignment across an organization. API governance strategies often start small, but then should evolve and grow to define, measure, and guide API operations across an organization. -

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 - Establishing a formal approach to how API governance is structured across an organization, providing a top down as well as bottom up structure for how API governance guidance is provided, but also how feedback on the guidance and approach to governance is gathered and woven back into the next iteration of API governance. -
  • Governance Leadership - It is important to establish who the leadership for organization-wide governance, determining who will be developing the strategy, evaluating feedback, and reaching out across the organization to help provide guidance when it comes to governance, while helping evolve and iterate upon the strategy based upon what is working and what is not. -
  • Governance Guidelines - Often published as API design guidelines, governance guidelines provide details on the standards for the design of APIs, but also provide guidance on documentation, testing, and other aspects of API operations. Providing a human readable document that is maintained centrally or across teams, helping API designers and developers understand what makes for good quality APIs.

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 - 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.
  • Documentation Rules - Machine readable or codified rules that govern whether or not documentation exists for each API, making sure there is accessible HTML documentation available for API consumers, and even validating there are examples, and other specific parts of API documentation present.
  • Management Rules - The governance rules to apply to API management, ensuring that policies are being applied consistently across APIs, standardizing how APIs are managed in production, making sure there are limitations, constraints, and observability present across all APIs in ways that are defined as part of a centralized governance strategy.
  • Testing Rules - Having machine readable or codified rules that ensure there is required testing in place for all APIs helps make sure that a baseline set of tests exist across all APIs, ensuring that contracts are upheld, integrations are maintained, performance is at acceptable levels, and there are not security vulnerabilities present in any API in production.

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 - Visual reports that aggregate data from across operations, making APIs and the operations around them something that team members can see activity, hisotry, and other dimension of what is happening across API operations, allowing different views to be organized and presented via dashboards.
  • Visualizer - The Postman visualizer can provide a visual response to any API response, allowing API calls made to be rendered as HTML, charts, and other visual elements, helping make API resources, capabilities, and the APIs themselves for visible.
  • Application Performance Management (APM) - The monitoring and management of performance and availability of APIs, actively detecting and diagnosing performance problems to maintain an expected level of service, translating API operational metrics into business meaning value at scale across hundreds or thousands of internal or external APIs.

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.


Discussions

YAML

Printable

Slide Deck

Return to Main Page

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