Low Level API Governance




Definition

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.

AsyncAPI

AsyncAPI is a machine readable specification for describing the surface area of your asynchronous APIs. OpenAPI is meant for describing synchronous APIs like REST using HTTP, and AsymcAPI is for describing websockets, MQTT, Kafka, NATS, and other syncrhonous, event-driven, and message APIs.

Application

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.

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.

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

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 operations objects 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 meeting 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.

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

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.

Collection Governance

A Postman collection for applying governance provides a flexible way to apply rules, schema, or script based governance, allowing governance to be defined as modular collections which can be manually run by developers, scheduled using a monitor, or easily dropped into a CI/CD pipeline.

CLI Governance

Governance can be applied at the command line interface (CLI) level, enforcing API governance locally during development, ensuring that APIs are 100% compliant with rules, contract, and script-based API governance established centrally as part of broader governance efforts.

IDE Governance

Governance can be applied at the integrated development environment (IDE) level, enforcing API governance locally during development, ensuring that APIs are 100% compliant with rules, contract, and script-based API governance established centrally as part of broader governance efforts.

Pipeline Governance

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

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.

The End