Managing the API Lifecycle Using OpenAPI and Postman
02 Aug 2020
I am having this conversation with over five separate API providers right now, so I wanted to write it up, share it as part of these conversations, while also making it available for my wider audience here on API Evangelist. I just finished another piece on managing your OpenAPI and Postman collection publicly, laying the foundation for this post. I want these to be separate modules which people can follow and use independently, providing me with a single URL for different concepts I am discussing. While this isn’t a a pattern everyone will want to follow, it is one possible pattern I’ve been identifying for use by companies looking to get a handle on how APIs are being delivered across the enterprise using Postman.
Building on an OpenAPI Foundation
The foundation of this blueprint is all about having an OpenAPI definition within a workspace acting as the central contract for each API. Providing the cornerstone each API will need to be moved along its lifecycle, and iterated upon by all stakeholders who have access to the workspace. You can view the separate post I have on management of OpenAPI using both Postman and GitHub, but here are the moving parts of what I propose for one possible blueprint for how you want to manage your individual APIs.
- Workspace - Always having a dedicated workspace for each individual API or a bundle of APIs, providing a single place internal stakeholders can find whatever they need about each API to understand how it works, and influence the road map when it comes to the future iterations.
- Repository - Ensuring there is a GitHub repository in place to act as the partner (private) or public face of each API workspace, providing a single place that external stakeholders can can to find information on APIs, and provide feedback on each API being made available.
- OpenAPI - There is a versioned OpenAPI contract in place for each API, publishing one or more APIs to a single workspace. Using Postman API builder to define the central contract for each API, then syndicating, generating, sharing, and syncing the contract for use in other systems.
- GitHub Sync - A two-way sync is set up to allow each OpenAPI contract to be synced to a GitHub repository, allowing changes to be made in both Postman and GitHub, but synced both directions, allowing for a bridge to exist between internal and external stakeholders.
This provides the foundation of the factory floor I am proposing with this blueprint. It gives you a single place to find each API, both for internal stakeholders, and with partners or public consumers of an API. It leverages Postman for much of the team work to move an API forward, and Github to manage the external facing elements of the API lifecycle. While depending on a machine readable contract as the source of truth within Postman, but also within any other system or pipeline using GitHub.
Powering the API Lifecycle from the OpenAPI Contract
Collections have always been the essential unit of compute within Postman. However, once we’ve started leveraging OpenAPI as the contract for each API in API builder, collections have been continuing to evolve in how they are applied, helping apply an API contract across the API lifecycle. Once I have a workspace, repository, and Open API setup for an API, I’ve begun requiring there be a handful of common collections that help me deliver each API, using a collection-driven, API-first lifecycle defined by these elements.
- Documentation - I am generating a collection from the OpenAPI contract specifically for managing and publishing documentation, providing a place to add examples and other details that help developers understand what is possible when it comes to putting an API to work.
- Mock Server - I am generating a collection from the OpenAPI contract specifically for managing and publishing a mock server for each API, providing me with an API I can use during design, development, and testing, providing me with a ready to go representation of each API.
- Contract Tests - I am generating a collection from the OpenAPI contract specifically for defining and executing contract tests for each API, requiring there be 100% coverage for all of the paths that are available for an API, ensuring they are delivering as expected in an ongoing way.
- Performance Tests - I am generating a collection from the OpenAPI contract specifically for defining and executing performance tests for each API, requiring there be at least one path tested, ideally multiple, for performance from one or more cloud regions to ensure optimal performance.
- Security Tests - I am generating a collection from the OpenAPI contract specifically for defining and executing security tests for each API, making sure 100% of the available paths are being tested for some of the most common security vulnerabilities that exist for our API infrastructure.
- Environments - There should be at least one, but ideally multiple environments available for applying against documentation, mock servers, as well as contract, performance, and security tests, allowing for multiple profiles and design, development, staging, and production environments to be used.
This further builds out the factory floor upon my OpenAPI foundation, providing what I will need to move each API forward in a consistent way. Ensuring that each API is well defined, documented, and fully tested to make sure it is meeting the needs of consumers. There will be additional stops along the API lifecycle such as deployment and management, but this blueprint can be applied to a brand new API that is being designed, all the way to an API that is in production. If every API I am developing uses this pattern, the potential for my factory floor to be further optimized, scaled, and distributed is much greater. I have a consistent foundation and machinery on my factory floor, which I can then replicate as separate workspaces for each API, each project, group, line of business, and organization. Providing me with what I need to scale API operations across many different teams, over many different geographic regions, serving many different applications.
Managing Change Across the API Factory Floor
The OpenAPI provides the contract needed to anchor each API throughout its lifecycle, providing a single source of truth for not just a single API, but multiple versions of the same API as it moves through time. Change is inevitable on the API factory floor, and this blueprint is designed to consider change, and make sure it is being managed at each step of the API journey. This blueprint focuses on a handful of ways that Postman can be used to deal with change, helping teams manage the forward motion of their API operations, using a couple of elements.
- Versioning - Each OpenAPI, and collection generated is versioned to help be proactive when it comes to change, embracing semantic versioning to help iterate on the design of each API in a way that can easily be communicated across the team, and externally with consumers as each API evolves.
- Validation - There is inline validation for each OpenAPI contract to make sure it is following the OpenAPI schema, as well as validation to keep each collection you generate in alignment with the central contract, ensuring that documentation, mocks, and tests are always in alignment with the OpenAPI contract.
- Syncing - Each version of an OpenAPI contract can be synced with GitHub, allowing change to occur within Postman, or externally as part of another system or application, allowing the OpenAPI contract to be syndicated and applied anywhere it is needed, leveraging Git as the conveyor belt for the API factory floor.
- Change Log - There is a change log built into each API documenting what has changed, allowing for a historical record of each API to be established, providing what is needed to understand, but also communicate what has changed with stakeholders and external consumers in real time, or as part of a review.
Change is an inevitable part of providing and consuming APIs. Whether or not API change is a positive or negative depends on your approach to managing it. The tooling and services you use will define change management for your teams, and set the tone for how your consumers view change--good and bad. This blueprint is designed to address the change that will occur across the API lifecycle, and the evolution of not just one, but of multiple APIs used across many different applications.
Establishing the Critical Feedback Loop You Need
This section of the blueprint is dedicated to making sure there is a feedback loop in place for all APIs, and all stakeholders are communicating properly around each stage of an APIs evolution. This blueprint makes sure that there is both an internal team feedback loop as well as a more external partner and public feedback loop that gives the community a voice. These are the feedback loop mechanisms that are in place as part of this API factory floor:
- OpenAPI Comments - Each OpenAPI has its own comment thread allowing internal stakeholders to be commenting on the evolution of each API.
- Documentation Comments - Each collection that is published for documentation has its own comment thread for internal stakeholders to use.
- Mock Server Comments - Each collection that is published for mock servers has its own comment thread for internal stakeholders to use.
- Contract Test Comments - Each collection that is published for contract tests has its own comment thread for internal stakeholders to use.
- Performance Test Comments - Each collection that is published for performance tests has its own comment thread for internal stakeholders to use.
- Security Test Comments - Each collection that is published for security tests has its own comment thread for internal stakeholders to use.
- Partner / Public Issues - The GitHub issues for the partner or public repo can be leveraged as an external stakeholder feedback loop for APIs.
- Workspace History - Each workspace provides a history of all API calls made through each of the collections made available to team members.
- Workspace Activity - All changes to API, collections, environments, and other elements are logged as part of workspace activity across teams.
- Reporting - There is reporting in place for all APIs, allowing me to see a history of their activity, broken down by API, helping define how each API is used.
A feedback loop is essential to moving an API forward. Without a way for both internal and external stakeholders to educate themselves about what is happening, and provide feedback on bugs, enhancements, and other elements, an API will not move forward and meet the needs of its consumers. Feedback from consumers is critical for making sure the API is going to meet the demands of applications and system integrations, and provides the raw material needed to build each version of an API.
A Factory Floor Designed for Collaboration by Default
Providing and consuming APIs is rarely an isolated effort. APIs developed in isolation often do not meet the needs of consumers, and APIs that aren’t easy to find, access, and put to use, rarely go anywhere. Successful APIs have active internal and external components, encouraging internal team members to actively collaborate, communicate, and interact, while also remaining engaged with external community stakeholders, ensuring they have a voice, and well-defined feedback loop in place to use. Here are some of the ways in which collaboration is built in as part of this API lifecycle blueprint.
- Workspaces - APIs can be found by team members using team workspaces, ensuring everything that is needed to work with an API is available within a dedicated workspace.
- Repositories - For the external facing engagement GitHub repositories can be used to provide artifacts, information, and use GitHub issues as a feedback loop.
- Workspace Sharing - Workspaces can be shared with other team members, providing them a single URL to find what they need to work with any API available within the organization.
- API Sharing - Each API can be shared with other workspaces, allowing management to be centralized, while sharing out access to other teams via workspaces, and using RBAC to control who can make changes.
- Collection Sharing - Each collection can be shared out to other workspaces, using RBAC to control who can edit or just use, but they can also be shared via URL, providing a quick way to make it available to other users.
- Desktop Sync - Postman users who are using the desktop application can work on APIs, collections, and environments within workspaces locally on their desktop and sync changes to the Postman platform for team access.
- GitHub Sync - Each OpenAPI can be synced to GitHub, enabling collaboration across other external systems, while keeping the changes in sync between the Postman workspace and the Github repository where the OpenAPI is synced.
- Documentation - Collections can be used to publish documentation, providing up to date details about an API, as well as examples and code snippets that can be shared with other consumers, helping them understand what is possible.
- Run in Postman Button - You can generate a run in Postman button from each collection that is generated from an OpenAPI contract, then publish the button on documentation, or any HTML or markdown page, allowing users to run in their Postman with one click.
- Private Network - APIs can be published to the internal network, allowing teams to build an internal organizational catalog of all the digital resources and capabilities that exist across teams.
- Public Network - Collections can be published to the public network, allowing the public to search for and import collections into their own personal or team workspaces, using collections to quickly on-board with public APIs.
Workspaces, APIs, collections, and environments are designed to be shared and worked on in a collaborative way. Encouraging internal team collaboration, as well as external partner or public engagement throughout the life of an API. Postman is a tool that has emerged as a developer favorite for working with APIs in isolation on the desktop, but over the last couple of years has evolved to incentivize teams to work together to move APIs forward within shared workspaces. When you combine this with the partner or public facing benefits of Github, you have the makings for a very robust and efficient way to design, develop, deliver, and sustain API infrastructure.
Realizing API Automation and Observability
This blueprint isn’t meant to be just a static snapshot of what the API lifecycle might look like. It is meant to be an executable blueprint that can be used to automate and make the API lifecycle more observable by publishing the results of each collection run. By defining individual types of tests like contract, performance, and security as individual collections, it allows for each individual area of the API lifecycle to be manually run, executed on a schedule in the cloud, or as part of other pipelines that are run as part of regular CI/CD process. Providing three distinct ways in which the lifecycle can be automated, depending on what the goals are for each individual API.
- Runners - All of the collections outlined as part of this blueprint can be manually run by any team member using a desktop or web runner, executing each collection, and the requests, scripts, and other details it contains using a variety of profiles defined as environments.
- Monitors - All collections can be run on a schedule from multiple geographic cloud regions, applying any profile defined as an environment, executing the requests, scripts, and other details a collection contains, reporting on the results of each cloud run.
- Pipelines - All collections can be run from any pipeline using Newman, the open source collection runner, executing each collection and environment, helping automate and make each stop along the API lifecycle more observable using the outputs from each run.
Runners, monitors, and pipelines provide us with the ability to automate the factory floor that moves each API forward. Working from a central OpenAPI contract, then generating, versioning, and validating each stop along the API lifecycle, we are able to choose to manually deliver a specific aspect of API operations, or schedule and execute upon different actions and events that occur as part of regular business operations. Giving us a significant amount of control when it comes to consistently moving each API forward, while making sure we are consciously managing change, and ensuring we are always meeting our API contractual obligation, as well as SLA when it comes to performance and security.
The Required Security Controls
This blueprint contains the base for a suite of security tests that can be automated, but there are a number of other security mechanisms built into Postman and this blueprint that help bring API security into focus, while providing some ways to help tighten the API security perimeter. These are the mechanisms in place for defining security for individual APIs, but also for applying in concert across many different APIs, helping keep things stable and secure for all internal teams, and external consumers.
- Security Tests - Each API will have at least one collection dedicated to security, ideally there are many different types of security collections that can be run in different ways, but each API should at least have one that is regularly monitored and reported upon.
- Public or Private - Teams can make a conscious choice to be public with an API, or keep it as part of a private network. Providing clear distinction and guidelines for how teams should be managing the presence for each of the APIs being delivered.
- Authentication - Each collection, folder, and request can possess the authentication details it needs to properly make each API request that is defined as part of an API, helping consistently apply authentication across API operations using well-defined collections.
- Environments - Collections should always have their keys, tokens, and other secrets abstracted away as part of environments, then applying the variables within each collection where they are needed. Helping keep sensitive data abstracted away from collections, with environments.
- Workspace Role Based Access Control (RBAC) - Each workspace has RBAC controls, allowing administrators to be able to control who can view or manage API workspaces.
- API Role Based Access Control (RBAC) - Each API has RBAC controls, allowing administrators to be able to control who can view, manage, or use APIs.
- Collection Role Based Access Control (RBAC) - Each collection has RBAC controls, allowing administrators to be able to control who can view, manage, or use collections.
- Environment Role Based Access Control (RBAC) - Each environment has RBAC controls, allowing administrators to be able to control who can view, manage, or use the environment.
- Activity - Everything done within a workspace is logged as part of activity, ensuring that there is observability into who is applying resources, allowing for security to be loosed or tightened at the workspace level, or more fine grained with APIs, collections, and environments.
The security portion of this API blueprint isn’t about providing a single silver bullet feature that can be applied to secure API infrastructure. This is about ensuring that all APIs are secured using the latest practices, and being able to define the security of each individual API request, as well as the workspace, APIs, as well as collections and environments used to work with and evolve each API. While also ensuring there is visibility into everything that is happening by default with all API activity across operations being logged and made more accessible within the workspace where teams are doing their work.
Managing the API Lifecycle Using OpenAPI and Postman
This blueprint is meant to provide one possible slice of the API operations pie. Showing how you can use OpenAPI as the central contract for each API, while defining, managing, and automating each stop along the API lifecycle using collections. This is the first time I’ve been able to actually demonstrate how you can move an API forward across the API lifecycle using common artifacts and tooling. Up until now most of what I have been preaching is academic hand waving, but I actually have this working as part of my Union Fashion reference implementation. I still have a lot of work to do when it comes to coherently demonstrating each section of this blueprint, but at least I have all the tools I need for my factory floor, I just have to get more consistent and coherent in how I demonstrate it, and help people apply to their own APIs.
There are a handful of critical stops along the API lifecycle missing from this blueprint. Primarily API deployment and management. I am working on fleshing out what management would look like depending on the cloud platform and API management solution you are using. Deployment is a much tougher nut to crack. I have successfully made a handful of API deployment collections that take the OpenAPI contract from each workspace and deploy the API to AWS. However, deployment is the toughest stop along the API lifecycle to define, so it will take me a significant amount of work before it comes further into focus. I would consider this to be my base template for managing my APIs using Postman. It really provides the fundamentals for my API-first approach to delivering APIs, and the deployment and management sections can be added later, allowing these stops to be more customized for the cloud you operate in, and which framework, service or gateway you put to work.
I still have a lot of work in better fleshing out the areas of this blueprint. I don’t feel like the relationship between OpenAPI and Postman collections is as clear as it should be. I don’t think that I’m adequately explaining how collections power the essential stops along the API lifecycle like documentation, mocks, and testing. I am just getting started on defining the feedback loop, collaboration, automation, and security aspects of this blueprint. However, this all gives me a pretty robust snapshot of what I am working with different enterprise organizations on. I will need to make it all a lot more modular before I present it to anyone, and be able to provide some sort of self-service walkthrough of what is going on before I think people will be able to follow. My goal is to keep investing in Union Fashion workspaces, and make it a working sample of what I am talking about, while heavily preparing and lobbying for new features in Postman that help make it easier for me to set up a working, clone-able example of this blueprint. Continuing to build my e-commerce reference implementation, but then quickly doing healthcare, and other industries to help show how this API blueprint can be applied to many different resources within the enterprise.