Governance is best developed from the top town, establishing common processes, rules, and guidance that reflect the architectural and business interests of leadership, but governance is realized at the lowest levels on the ground floor of operations, and it also makes sense in many organizations to set in motion some low-level governance patterns while higher level governance is being established. This blueprint is meant to walk through how your average API developer might approach governance as part of their regular work, helping them design and deliver more consistence APIs as part of a more high level governance approach or in absence of a more high level governance approach. Helping API teams learn how to step back and look at how they can define what a good API is and then deliver on that vision consistently as part of a high velocity release schedule. Setting the stage for a low level approach to implementing API governance that can work in alignment with higher level strategy, or begin moving the API governance from the bottom up.
You can't govern what you don't have define, and to be able to begin governing the design of your APIs you will need to have machine readable artifacts that you can lint as part of the design, develop, or build process. Establishing a set of artifacts that help drive the API lifecycle, but also make it something that can be measured and reported upon as part of governance activities.
- 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.
Once you have an OpenAPI, AsyncAPI, or other artifact that you would like to apply governance too, there are a handful of ways in which you can execute governance as part of your regular work. Depending on your goals with governing the design of an API you can apply each of these elements helping manual or automatically identify problems with the design of your API. These approaches to execution are potentially dependent on other rules, as well as the approach you take to automating the application of governance.
- Rules-Based Linting - Rules-based linting allows for the defining of YAML or JSON rules for elements of API governance and applying them in a programmatic way against OpenAPI, AsyncAPI, and other machine readable artifacts, helping apply desired constraints to the design or other area of the design, development, and operation of an API.
- Contract-Based Linting - Contract-based linting allows for the validation of OpenAPI, AsyncAPI, and other artifacts used as part of the API lifecycle against specific contracts as defined by JSON Schema, providing a definition of what should exist as part of the design for each API, but done in a way that allows it to be verified across the API lifecycle.
- Script-Based Governance - A script-based approach to governance involves using the same collection based approach used to apply contract, performance, and other types of testing with Postman collections, but instead of testing an instance of an API, you are testing the surface area of the API by pulling the OpenAPI and writing test scripts for specific governance assertions.
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.
- 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.
- License Governance Rules - Rules can be defined to govern the license details provided for each API, leveraging the license object for OpenAPI or AsyncAPI contracts, but then apply specific ruling looking for common patterns to be present like the license type or url of an API, meeting specific guidelines regarding what license is needed.
- Description Governance Rules - Rules can be defined to govern the descriptions provided for each API, leveraging the description properties for OpenAPI or AsyncAPI contracts, but then apply specific ruling looking for common patterns to be present like length or contents of the description, meeting specific guidelines regarding what description 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.
- 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 meeting specific guidelines regarding what is expected of a parameter.
- 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.
To realize governance across operations it is important that governance is applied in automated ways at different areas of the API lifecycle, helping ensure API governance can be applied early on in the lifecycle, but is also available throughout the development and delivery of aPIs, and when it makes sense bake it into the build process ensuring that governance is applied by default as every API moves into production. Helping ensure that teams aren't doing extra work to realize governance across operations, and it is just at their fingertips as they are design, developing, and building APIs as part of their regular day.
- Design Time Governance Automation - Governance can be applied and automated at design time, providing real time or manually triggered application of governance rules, contracts, and scripts, providing a tighter feedback loop with API designers in regards to the guidance around what is expected of the design of each API.
- Develop Time Governance Automation - Develop time API governance automation allows for the applying of rules, contracts, and script-based enforcement and guidance of governance, helping developers deliver more consistent APIs as they are developing them using a more traditional software development lifecycle.
- Build Time Governance Automation - Governance can be applied at the pipeline level, enforcing API governance at build time, ensuring that APIs are 100% compliant with rules, contract, and script-based API governance established centrally as part of broader governance efforts.
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.
This blueprint looks at how you can approach API governance as an individual, learning about the building blocks of how governance can be applied when it comes to designing, developing, and operating individual APIs. 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.