Low Level API Governance

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.

Define

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 acts as the contract for any HTTP API, providing a machine readable way to describe the details of each request and response in a way that can be used across the entire API lifecycle. OpenAPI can be introduced in different ways via the API lifecycle, but once introduced should be managed as the source of truth for each API, always keeping up to date and managed via Postman workspace as well as synced to relevant repositories. The OpenAPI for each API can be used to generate collections for documentation, mocking, testing, and other areas of the API lifecycle, providing executable representations of each API tailored for a specific purpose, while maintaining a single source of truth for the contract of each API that can be used to keep docs, mocks, and tests in sync, but also to validate that each API contract is being met.

Execution

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 is a preferred way of applying linting to any OpenAPI, AsyncAPI, or other machine readable contract for an API because it allows common rules to be defined as YAML or JSON, then applied consistently across all APIs using a linting library or API. Linting rules help establish a baseline for what governance is across an organization, but then allow individual developers to apply and check for violations of these rules as part of their regular API development process. This approach helps catch common challenges with delivering consistent APIs across teams, and help developers achieve more alignment in how APIs operate, no matter what team they were developed by.

Contract-Based Linting

JSON Schema can be used to define specific patterns that should exist within each OpenAPI or AsyncAPI contract being defined as part of the design, development, and operation of an API. Contract-based always begins with adhering to the specification for OpenAPI or AsyncAPI using their own JSON Schema document, but is something that can be extended to other patterns like pagination, extensions, or domain specific design pattern. A contract-based approach to governance can assist in going beyond rules based governance by allowing for more complex patterns to be checked, but utilizes existing approaches used across other areas of the API lifecycle, making it something within reach of teams. Helping establish a common set of patterns that can be applied manually or automatically throughout the life of an API to help make sure it applies common API design practices within an organization or industry.

Script-Based Governance

A script-based approach to applying governance to any OpenAPI or AsyncAPI is the flexible approach to governance allowing for almost any type of assertion or desired outcome, but will require custom scripting to define each governance assertion. The OpenAPI or AsyncAPI for an API can be pulled via a URL or the Postman API, and then test scripts can be written to traverse and apply a variety of custom assertions, looking for problems in the design of each API. As with other API testing, the test results pane or visualizer can be used to report on the findings, alerting the developer that something is wrong with the design and what needs to be fixed, or throw an error to trigger the failure of a pipeline at build time. A script-based approach to governance will provide the widest flexibility, but require the most investment to develop the scripts needed to enforce governance across known API artifacts.

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.

Info Governance Rules

Info governance rules provide a base of YAML or JSON rules that can be applied to the info object within OpenAPI or AsyncAPI contracts, checking for specific patterns for the title, description, and other elements of an API. Rules can be defined centrally by governance leadership, or locally within teams, and then applied either at design, develop, or build time in a manual or automated way depending on the objectives of team, department, organization, or industry-wide governance.

Contact Governance Rules

Contact governance rules provide a base of YAML or JSON rules that can be applied to the contact object within OpenAPI or AsyncAPI contracts, checking for specific patterns for the contact name, email, link, and other elements of an API. Rules can be defined centrally by governance leadership, or locally within teams, and then applied either at design, develop, or build time in a manual or automated way depending on the objectives of team, department, organization, or industry-wide governance.

License Governance Rules

License governance rules provide a base of YAML or JSON rules that can be applied to the license object within OpenAPI or AsyncAPI contracts, checking for specific patterns for the license type, url, and other elements of an API. Rules can be defined centrally by governance leadership, or locally within teams, and then applied either at design, develop, or build time in a manual or automated way depending on the objectives of team, department, organization, or industry-wide governance.

Description Governance Rules

Description governance rules provide a base of YAML or JSON rules that can be applied to the description object within OpenAPI or AsyncAPI contracts, checking for specific patterns for the length or contents of a description, and other elements of an API. Rules can be defined centrally by governance leadership, or locally within teams, and then applied either at design, develop, or build time in a manual or automated way depending on the objectives of team, department, organization, or industry-wide governance.

Path Governance Rules

Path governance rules provide a base of YAML or JSON rules that can be applied to the path object within OpenAPI or AsyncAPI contracts, checking for specific patterns for words used to describe a path, restricting acronyms, enforcing unique ids, and other elements of an API. Rules can be defined centrally by governance leadership, or locally within teams, and then applied either at design, develop, or build time in a manual or automated way depending on the objectives of team, department, organization, or industry-wide governance.

Parameter Governance Rules

Parameter governance rules provide a base of YAML or JSON rules that can be applied to the parameter object within OpenAPI or AsyncAPI contracts, checking for specific patterns for the parameter name, description, and other elements of an API. Rules can be defined centrally by governance leadership, or locally within teams, and then applied either at design, develop, or build time in a manual or automated way depending on the objectives of team, department, organization, or industry-wide governance.

Schema Governance Rules

Schema governance rules provide a base of YAML or JSON rules that can be applied to the schema object within OpenAPI or AsyncAPI contracts, checking for specific patterns for the schema name, description, and other elements of an API. Rules can be defined centrally by governance leadership, or locally within teams, and then applied either at design, develop, or build time in a manual or automated way depending on the objectives of team, department, organization, or industry-wide governance.

Automation

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

It is best to provide governance feedback as early on in the lifecycle as possible, and automating governance at design time as part of the editor or IDE as a real-time intellisense feedback loop, or manually triggered to evaluate an OpenAPI or AsyncAPI being designed is a common approach to realizing governance at design time. Providing design time governance feedback and automation helps not just enforce rules, contracts, and script-based approaches to governance, it helps educate and make designers more aware of governance guidelines and why they exist. Making for a pretty significant opportunity to apply governance before any API ever reaches the development phase.

Develop Time Governance Automation

Not all APIs will experience a design phase, with many moving forward as part of a code-first or more traditional software development lifecycle, making develop time governance another way to enforce and enable teams when it comes to helping deliver more consistent APIs. Develop time governance automation still requires there to be machine readable artifacts like OpenAPI or AsyncAPI present, generated using annotations or other approach, but then allows developers to apply rules, contract, or script-based governance to the API they are developing. Automating the guidance around government in a way that works seamlessly with developers existing software development practices, allowing them to do what they do best, but regularly check to make sure they are in alignment with team, department, organization, or industry API governance practices.

Build Time Governance Automation

The enforcement of API governance at the pipeline layer is not ideal in all situations and organizations. Still, it is a very desirable objective for realizing consistency in delivering APIs across an organization. Rules, contracts, and script-based governance can be codified into specific collections and then easily executed as part of the pipeline, ensuring that the OpenAPI or AsyncAPI contract for any API build aligns with a wider governance strategy. Pipeline enforcement is the desire of governance leadership at the higher levels. Still, it will take a considerable amount of work to achieve without introducing friction across teams doing the hard work to keep API operations moving ahead at the desired velocity.

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 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.