A blueprint for approaching 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.
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 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 ever be complete, but more of an ongoing journey for an organization to define itself.
- Domains - The establishment of domains within the enterprise, allowing for logical separation of business concerns as dictated by the domain experts, helps prevent information overload, unnecessary dependencies, and other challenges that arise due to sprawl and complexity across the enterprise. null
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 the greatest impact. To do this, you have to invest resources, time, and people to help 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 - Providing a clear structure for how governance will be executed, balancing efforts across a top-down, but then also a bottom-up approach to moving things forward. Establishing an agreed-upon scaffolding for how everyone will work together to govern the design, documentation, testing, and other elements of API operations in a consistent way.
- Governance Leadership - Establishing a group of individuals from across the business and technical leadership, bringing together a mix of skills and domain expertise together to work on the overall API governance strategy, meeting regularly, and actively communicating across teams who are helping lead API governance efforts.
- 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. null
API governance rules codify 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 of governance and organization is moving towards.
- Design Rules - Machine-readable rules that can be applied at design, development, 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, and 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.
- Info Governance Rules - Rules can be defined to govern the information provided for each API, leveraging the info block for OpenAPI or AsynCaPI contracts, but then apply specific ruling looking for common patterns to be present like the title and description of an API, meeting specific guidelines regarding what information is needed.
- Contact Governance Rules - Rules can be defined to govern the contact details provided for each API, leveraging the contact object for OpenAPI or AsyncAPI contracts, but then apply specific ruling looking for common patterns to be present like the contact name, email, or URL of an API, meeting specific guidelines regarding what contact is needed.
- Versioning Governance Rules - Rules can be defined to govern the information provided for each API, leveraging the OpenAPI or AsynCaPI contracts, but then apply specific ruling looking for common versioning patterns in the path, parameters, headers, and other details of an API, meeting specific guidelines regarding what information is needed.
- Path Governance Rules - Rules can be defined to govern the paths provided for each API, leveraging the path object for OpenAPI or AsyncAPI contracts, but then apply specific ruling looking for common patterns to be present like words used, ensure no acronyms exist in the path, meeting specific guidelines regarding what a path can contain.
- Operations Governance Rules - Rules can be defined to govern the operations provided for each API, leveraging the objects of the operation for OpenAPI contracts, but then apply specific ruling looking for common patterns to be present like summary, description, operation ids, and other elements of operations.
- Parameter Governance Rules - Rules can be defined to govern the parameter details provided for each API, leveraging the parameter object for OpenAPI or AsyncAPI contracts, but then apply specific ruling looking for common patterns to be present like the parameter name and description meet specific guidelines regarding what is expected of a parameter.
- Request Bodies Governance Rules - Rules can be defined to govern the request body details provided for each API, leveraging the request body object for OpenAPI contracts, but then apply specific ruling looking for common patterns to be present like whether it should have a body, the media type, example, and other details of an API, meeting specific guidelines regarding what contact is needed.
- Response Governance Rules - Rules can be defined to govern the response details provided for each API, leveraging the response object for OpenAPI or AsyncAPI contracts, but then apply specific ruling looking for common patterns to be present like the status code, media type, and other details of an API, meeting specific guidelines regarding what responses should look like.
- Schema Governance Rules - Rules can be defined to govern the schema details provided for each API, leveraging the schema object for OpenAPI or AsyncAPI contracts, but then apply specific ruling looking for common patterns to be present like the schema name and description meeting specific guidelines regarding what is expected of a schema.
- Tags Governance Rules - Linting governance rules that focus on making sure that API artifacts like OpenAPI and AsyncAPI are applying tags to elements of the API, ensuring that operations and other elements are able to be filtered and organized based upon different characteristics allowing documentation to be organized, grouped, and presented in a logical way, helping reduce complexity and make APIs more accessible to consumers. null
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.
- APM -
- Reports - Visual reports that aggregate data from across operations, making APIs and the operations around them something that team members can see activity, history, and other dimension of what is happening across API operations, allowing different views to be organized and presented via dashboards.
- Activity - The changes made to any aspect of operations by team members, provide observability into when APIs, mock servers, documentation, testing, monitors, and other critical elements of API operations are changed and configured-- helping give a log of everything that happens at the operational level.
null