Getting More Hands-On Talking About API Governance
17 Aug 2020
I am getting more hands-on with my API governance guidance while working at Postman. It is one of the reasons I joined the company, so I could move more into the execution of my API lifecycle strategies, which also includes applying API governance. To showcase some of what I have been developing I am doing an API governance webinar this Wednesday. To help me polish the narrative around my talk, as well as my wider API governance guidance, I wanted to work through my current narrative here on the blog. What I am enjoying most about my narrative right now is that they are rooted in doing what I am talking about, allow me to get more hands-on with API governance, where for much of the last five years my stories have just been narratives without much meat on the bone. I am enjoying this shift from a more academic perspective to actually being able to deliver what I am talking about when I say API governance.
An Intro API Governance
Most people will go straight to API design governance when they begin talking about governance, but I prefer starting with the base of API governance that is already in motion across many API operations. Born out of an API-first approach to delivering infrastructure many teams are already delivering on governance, they just call it other names like versioning and contract testing. This is definitely the road to API governance, but it is lacking an overarching API governance strategy to effectively deliver across many different APIs developed by many different teams. To help paint the tactical API governance that is already occurring let’s zoom in on a single API being developed using an API-first approach, and consider how it is laying the foundation for a wider and more strategic approach to governance how APIs are delivered.
- Workspace - Having a dedicated repository and / or workspace for an API provides the base for delivering APIs consistently.
- OpenAPI - The OpenAPI specification provides a common vocabulary for defining, communicating, and governing APIs.
- Versioning - Having a strategy for managing change across individual APIs is essential to governing API operations.
- Mocking - Being able to articulate the next iteration of each API in a functional ways helps drive governance of APIs.
- Documentation - You have to be able to effectively communicate to other human beings what an API does before you can govern.
- Code Generation - Code generation helps deliver consistent behavior in the applications and integrations build on each API.
- Contract Testing - Testing your API definitions ensures that you are consistently delivering against each promised API contract.
This is a snapshot of governance practices already in place across enterprise API teams today. It doesn’t speak to the design of an API, but it does provide the basis for not just being able to govern the design of an API, but how it is developed, communicated, tested, and made available for use in client applications and integrations. You can’t govern the design of an API without a machine readable contract like OpenAPI that is versioned over time. Then it doesn’t matter if you are governing your API, if you aren’t providing documentation and consistent client tooling, and making sure to test the contracts of each API you deliver. All of this is the foundation for API governance, the design API is just the aspect of API consumption that introduces the most friction when it comes to API operations.
What is API Design Governance?
The design of the surface area of an API is what comes to mind for most people when you talk about API governance. Inconsistent API design patterns across a single organization’s APIs is one of the most common types of friction introduced into the software development lifecycle. When APIs share common patterns it becomes easier for developers to understand how to put them to work. The entire reason the current pattern of REST APIs has become the dominant pattern in use is because it is simple, consistent, and relies on the HTTP standard. API design governance is very focused on producing the best quality API as possible by refining some of the most common ways in which APIs are leveraged, governing the surface area for the request and the response of each API method.
- Paths - Ensuring the URL Path is intuitive, simple, and well thought out as part of an organization wide strategy for delivering digital resources.
- Methods - Leveraging GET, POST, PUT, DELETE, and other common HTTP methods when working with digital resources being made available via an API.
- Parameters - Having a strategy for how parameters are leveraged, crafted, and used across all APIs, helping ensure consistent path and query parameters.
- Request Body - Being thoughtful in how and when the request body is used as part of API requests, using the body as the payload, complimenting parameters, headers and HTTP methods.
- Response Body - Providing a standardized way of returning JSON, XML, or other data returned as part of each response, keeping responses consistent across all APIs, standardizing what developers can expect.
- Status Codes - Always using appropriate HTTP status codes, effectively communicating with client integrations, providing information, success, redirect, and client or server problems encountered with each request.
There are many other areas that can be included in API design governance, but these are the areas that are top of mind for most API providers and consumers. API design governance is all about standardizing how APIs are delivered, helping reduce friction and overhead when it comes to documenting, mocking, testing, securing, and integrating with APIs. Reducing the number of surprises a developer might face when putting an API to work, employing patterns developers are already familiar with, and do not require additional cognitive load to begin putting to use. As outlined above, you can’t measure what you can't find and make sense of, in a machine and human readable way. Meaning, if you don’t have a versioned OpenAPI in a known workspace, you won’t be able to realize API governance, let along the design slice of the API governance pie.
Measuring API Governance
OpenAPI, and an API-driven lifecycle is critical to being able to govern APIs at scale across an organization. You can’t govern something you don’t have defined. You can’t govern something you can’t programmatically ask a question of. OpenAPI has emerged as the central specification format used by API providers to define the surface are of their HTTP APIs, providing the foundation for how we define, measure, and report upon how we are doing when it comes to the design of each API being delivered on the enterprise factory floor. Similar to each instance of an API, an OpenAPI provides us with a machine readable format that we can test to ensure that we are following prescribed design practices for each of the APIs we are developing. Providing a machine readable contract for not just the resources we are making available via each API, but for the API design itself.
- OpenAPI - The OpenAPI specification is the machine readable contract you will need to define, measure, and ultimately govern how APIs are designed.
- Requests - Each API governance rule can be defined as a single API request, pulling the OpenAPI contract for an API, providing the basics for governance.
- Test Scripts - Test scripts can be developed to evaluate the details of each API contract, evaluating whether or not it meets API governance standards.
- Test Results - Results can be accumulated from across many individual API governance requests made of the OpenAPI contract, reporting across each API.
- Environments - Environments are used to provide secrets and other variables needed to measure API governance, and used as a store for the results.
- Collections - Each suite of API governance requests are defined and stored as a collection, providing a single executable unit of API governance for use across API operations.
API governance using Postman provides you with a machine readable way to ask and answer your API governance questions. As with each other stop along the API lifecycle you can use OpenAPI as the contract for each API, while using a collection in combination with an environment to realize governance across API operations. The OpenAPI is the contract for defining and validating each individual API instance, but it is also what keeps each individual API in alignment with other APIs, providing a common vocabulary for speaking about governance of resources being made available via APIs. Providing a self-contained, machine readable representation of how an API should be designed and behave, which can be manually run by developers to see if the API they are working is compliant with wider API governance, or scheduled and automated to run as part of regular processes.
API Governance Automation
With API governance defined as a self-contained executable collection opens up the possibility for automation and orchestration of API governance across operations. Like the testing of individual API instance, API governance should be scheduled, automated, and build into our API delivery pipelines. This is why using the same services, tooling, and definitions used to test each API implement makes sense for defining, measuring, and reporting upon API governance. Postman collections plus environments provides the fuel for this API governance automation, but then runners, monitors, and Newman helps actually automate the governance of API infrastructure. Helping ensure that API governance can be scaled in a consistent manner across organizations, lead from a centralized organization, but then applied, refined, and reported upon from within each individual API workspace and team.
- Collections - API governance collection provide a machine readable set of requests that can be made of each API contract, that can be executed as a single unit of governance.
- Environments - A Postman environment is used to define governance, but then also aggregate and store results so that they can be reported upon by individual developers or as part of wider governance.
- Runners - Postman runners allow individual developers to run a governance collection locally on their desktops or via the Postman web interface, helping understand if an API is compliant with wider governance rules.
- Monitors - Postman monitors allow for the scheduling of API governance collections and running them in different cloud regions, helping regularly test to see if an API is compliant with wider governance practices.
- Pipelines - Lastly, collections can be executed within CI/CD pipelines using the open source Newman runner, executing API governance at the pipeline level, ensuring no APIs move into production that haven’t met API governance.
- Infrastructure APIs - The APIs for the infrastructure used to deploy and manage APIs can be further used to automate and report on API governance, providing additional artifacts that can be stored, measured, and reported upon.
While API governance automation isn’t necessary early on in the API governance journey, it is essential further down the road. API governance can be seen as a hinderance by developers if not fully fleshed out and providing sufficient details about why an API hasn’t met governance rules. So be cautious in automating it early on until API developers are fully educated regarding how to implement it, and processes for applying and reported operate smoothly. However, once a robust set of rules have been defined, and teams are successfully applying manually within their Postman clients, API governance collections should be regularly scheduled using monitors, and put into every CI/CD pipeline used to deliver the code behind APIs, or driving API gateway deployment and management. API governance testing should just be another layer of testing that is realized as part of the automated software delivery lifecycles already in place across the enterprise.
Reporting on API Governance
After collections are run, the results will need to be reported upon, helping everyone involved understand the state of API design for each API, across teams, and an organization. Along with the collection and environment capabilities, Postman provides the ability to store the results of API governance, and report on them using Postman visualizer. Providing a self contained way of defining, executing, and reporting on API governance in a consistent way across many different APIs.
- Environments - Postman environments are used to define and store API governance, providing a key/value store that can be used along side development, staging, and production environments, but providing an added dimension that covers governance needs.
- Visualizer - The Postman visualizer can be used to deliver reports across all of the API governance requests being made, providing a visual way to understand how well governance is being applied, and realized across operations by each team.
Expanding on API Governance
A dedicated workspace, OpenAPI, and some design governance should just be the beginning for most teams. If each stop along the API lifecycle is API-driven then there are always artifacts available which can be used to define, measure, and report upon each area of API operations. Enterprise organizations should focus on ensuring there are robust OpenAPIs available for all APIs, that are easily discoverable, and find their footing when it comes to defining, educating, applying, and reporting on healthy API design practices. Once teams have found their way when it comes to API design governance across APIs, then they can begin looking at the other aspects of API operations that should be governed, moving the focus of API governance to the following areas.
- Workspaces - Whether your API workspaces are a GitHub repository, and Postman team workspace, or some other platform, it should have an API. Allowing for the configuration and orchestration of APIs within their workspaces.
- Mocking - Measuring whether teams are mocking their APIs as part of an API-first design process, on-boarding new developers, or as part of API testing, and working to govern how APIs and data are virtualized.
- Documentation - Robust, complete, and always up to date API documentation should always be present for APIs, and API governance should be measuring and monitoring the quality of documentation published for each API.
- Testing - 100% of the surface area of an API should be tested, ensuring that int is always in alignment with its OpenAPI contract. API governance should be measuring and monitoring the state of API testing across all APIs.
- Monitoring - The orchestration of the API lifecycle, and the deployment and configuration of monitors executing a variety of tasks across API operations should be defined, measured, and reported on as part of a wider strategy.
- Pipelines - API governance should live within the pipeline, and be measured and reported on, helping make sure there is 100% governance being applied by default across all APIs, baking governance into the deployment of all API infrastructure.
Adopting OpenAPI across API operations is the beginning of the API governance journey, and versioning and then testing your APIs represents the forward motion of API governance across your teams. API design governance becomes possible at a stage of the journey where OpenAPI contracts are present, up to date, and regularly tested. Most API providers are currently doing many of the moving parts of API governance, they just aren’t doing it as part of a wider API governance strategy, and in a machine readable way that can be tested, automated, scaled, and orchestrated as part of a distributed API governance effort.