A co-worker of mine Bob Fahey said a customer had asked what the twenty problems that Postman is solving for developers in 2022. I am in writing mode this afternoon so I figured I’d craft a post to try and articulate twenty of the common problems we were solving this year. I will most likely rewrite it for an official Postman blog post, but I wanted to cut my teeth on a meaningful list to share right away. API Evangelist is very much my playground for storytelling, allowing me to explore using my words to describe a variety of concepts, and then work on a more polished and coherent post for the official Postman blog when ready. Hopefully, this post can whet your appetite regarding what is possible when it comes to the problems that we are tackling at Postman when it comes to the development of APIs and the applications and integrations they power.
Seeing Your APIs
APIs are extraordinarily difficult to see. You might be able to see the response of an API using a client like Postman, but seeing the surface area of an API to know how to make a request can be very, very difficult, depending on the scope and complexity of the API. Postman gives you the controls to define and probe the surface area, understand the authentication, query parameters, path parameters, headers, and other technical details. Once you’ve successfully described the surface area of an API you can save that as a collection, which provides a visual interface for working with an API without having to write code. Collections allow you to “see” the surface area of your APIs, complete with documentation and visualization, but defined in a way that allows you to reuse, share, and work with as part of producing or consuming APIs.
Finding Your APIs
API work occurs across desktops and servers spread across the enterprise and the cloud. The average enterprise has thousands of APIs available across multiple domains, making finding APIs, their artifacts, and other resources a time-consuming affair. Postman makes not just the APIs easier to find via private and public catalogs or what we call networks, but also the workspaces that teams are using to design, develop, operate, and automate using APIs. Postman allows teams to publish their APIs to private or public networks, and soon-to-be partner networks, and keep the team, artifacts, documentation, tests, mock servers, monitors, and other elements discoverable by default. You don’t have to go looking for APIs across different repositories, file systems, servers, and other locations, you can find them in a single network location, and via search. Postman significantly reduces the time it takes for teams to find APIs before they develop new ones, reducing redundancy across operations, but also finding them when APIs are needed as part of new web, mobile, and device applications, as well as a system to system integration.
Talking About Your APIs
Like finding your APIs, discussion about APIs between API producer and consumer, across teams who are developing with them, with partners, and other stakeholders can be a dizzying and complex endeavor. Conversations about the technical details of each API aren’t easy to have in an accurate way, helping get everyone on the same page. Postman provides the ability to comment and mention team members natively as part of each OpenAPI artifact, as well as the collections derived from them to produce documentation, mock servers, and tests. Postman comments allow teams to highlight specific sections of the OpenAPI, and leaving inline comments makes API discussions more precise and productive. Providing a single place where teams can engage to push forward the design of an API, obtain peer reviews for test scripts, and direct team members to accomplish specific tasks. The Postman API platform is changing the tone of how we talk about our APIs, helping get everyone on the same page and moving in the right direction.
Documenting Your APIs
Postman provides a solution for the number one pain point developers experience—creating API documentation, and keeping it up to date. But, Postman doesn’t provide last generation documentation that you publish to a single API portal, it provides you with the documentation generated from your OpenAI, RAML, other API artifacts, but then allows you to share, embed, execute, and keep up to date in real-time with the work you have occurring via your API workspaces. The Postman platform provides dynamic and interaction documentation but the kind that is more portable, executable, and keeps up with the pace of change across the enterprise. Postman documentation can be embedded via developer portals, but also via wikis, blog posts, and as part of regular operations, allowing documentation to be quickly shared with other team members and consumers. Providing documentation that isn’t just a complete reference of what is possible with each API, but also onboarding API document designed for new consumers, or possibly versions of documentation meant just for partners. Offering a more flexible, evolvable, and precise approach to API documentation that grows with the needs of your operations.
Collaborating Around APIs
The Postman platform always begins with developers working in isolation, but the greatest benefit it provides developers as an organization evolves in its API journey is the ability to collaborate within workspaces, across source control, and multiple gateways. Teams can be organized by groups in alignment with domain-driven design, lines of business, and other organizational constructs, then workspaces and repositories can be shaped to match team size, structure, and how they are moving APIs forward. Providing very organized approaches to collaborating around OpenAPI, GraphQL, gRPC, Websocket APIs using workspaces, comment feedback loops, notifications, and the activity, history, and observability that gets introduced across API operations. Reducing the cognitive load when it comes to the information available around APIs, but then bringing the conversation and coordination around each API locally into well-defined workspaces that fit into the overall organizational plan for moving the enterprise forward.
Confidently Sharing APIs
Sharing access to APIs that are being developed with business and technical stakeholders can take a significant amount of work via a private, partner, and public developer portals. The Postman API platform makes it easy to quickly share API documentation, mock servers, tests, monitors, and other assets private, with partners, and publicly via workspaces, embeddable buttons that allow consumers to fork interactive documentation, and via simple URLs. No more sharing via email, sharing Postman collections via workspace, buttons, and URL allow for APIs to be forked, executed, and automated by consumers without having to write any code. Postman collections aren’t just solving the issue of sharing APIs for developers, it is opening this same benefit up for business users as well. Providing a shareable and executable unit of value that can be run with a single click, saving the data output, rendering it using visualizer, or simply interacting with APIs to put enterprise capabilities to work. Sharing is an essential part of API operations which can reduce friction for API producers and consumers when it comes to engaging across the lifecycle, private, public, and confidently with an intended audience.
Making APIs More Consistent
One of the most important features developers should be taking advantage of within Postman is the ability to test and validate not just the responses from each API, but also the consistency in the surface area of the API. Postman allows you to pull the OpenAPI for any of the APIs you are managing via the Postman API, which allows any developers to use a test script and the JSON Schema present in the OpenAPI to validate that there are no breaking changes available. Postman provides the ability to manage multiple versions of each API, which can then be easily pulled and compared to see if API contracts are changing with each release, even before you push to production. Many call this API design governance, but being able to test and validate the surface area of your APIs is more about ensuring that developers are being consistent in how they design APIs, but also allowing them to catch inconsistencies earlier on in the API lifecycle and then collaborate and communicate around those changes with their team and consumers.
Syncing APIs with Source Control
Source control is the center of operations within many enterprise organizations, leveraging Github, Bitbucket, or GitLab as a source of truth for the code behind applications and integrations. The Postman platform seamlessly integrates and syncs OpenAPI and collections with source control, ensuring that machine-readable artifacts that are available via workspaces are also available via repositories for use in CI/CD workflows. Git sync is helping developers augment the existing software development lifecycle with the API lifecycle, and use artifacts for publishing APIs to gateways, testing APIs, and other needs of developers as they develop and deploy APIs. API artifacts like OpenAPI and collections provide developers with contracts that define what APIs are capable of, but also what is needed to ensure the quality and consistency of APIs, as well as allowing for the automation across the API lifecycle. All of which helps reduce the work developers are needing to do during development, allowing them to focus on the core business functionality they are looking to deliver.
Quantifying Your API Releases
Git and CI/CD pipelines have changed the enterprise landscape when it comes to making software releases much more repeatable affairs, allowing for much greater velocity when it comes to releases. The Postman API platform provides the same release tooling but for the API layer of the software development lifecycle, allowing multiple changes to APIs to be rolled up into a single release, helping communicate the change that is occurring. Managing change is difficult, and it helps to have a release mechanism for articulating exactly what the atomic changes were for each individual API, and then publish and communicate each release, and include it in a changelog. Helping developers be more explicit when it comes to defining and communicating change, then making it available for other developers and stakeholders to find in the API workspace housing each API. Making change across API operations much more tangible and real, helping API producers and consumers stay up to speed on what is happening when it comes to the evolution of each API.
Managing Change for Your APIs
Managing change across a single API is difficult, but doing it across hundreds or thousands of APIs is extremely challenging. You simply cannot do it without a platform approach to versioning many different API artifacts which act as the source of truth for each API, but also the lifecycle elements like documentation, mock servers, and tests that surround them. The Postman API platform provides the ability to version your API artifacts, as well as the collections that power the elements of the API lifecycle, allowing you to apply semantic or date-based versioning to APIs. This versioning is available for producers to use to manage and communicate change, but is also available to consumers via private or public workspaces to understand change as it is happening across the API they depend on. Postman allows for managing change across APIs in a way that can be synced via existing source control and CI/CD solutions, but also automated and leveraged as part of API operations using the Postman API—allowing for change management to be scaled across API operations in a consistent way.
Help Increase Your API Quality
API testing is in Potman’s DNA, with collections and embedded test scripts acting as the essential building block of contract, integration, performance, security, and many other types of API tests. Developers can define very granular level API testing for each API to test individual API responses, as well as stitch together common business workflows into a more complex series of API tests that ensure essential business capabilities are performing as expected. API testing using Postman collections is something every developer can implement within workspaces, and then manually run using Postman runners, scheduled to run from multiple cloud regions using monitors, or baked into the CI/CD pipeline using our open-source collection runner Newman. The existence of tests can be visualized using enterprise reporting, the results of monitors can be piped into existing APM solutions, and test results at scale across APIs can be aggregated via any 3rd party service that possesses an API, helping teams understand quality at scale across operations. Providing very localized testing for API developers that can be woven together into a team-wide, as well as an organization-wide approach to realizing quality across the enterprise.
Shifting API Security to the Left
APIs are increasingly responsible for data breaches across enterprise organizations, pushing organizations to work to better equip API development teams with the resources they need to properly secure API infrastructure as it is being released. Postman users are increasingly using collections as a way to implement security as part of the API development process, with more enterprise organizations requiring there be a collection available to scan the surface area of an API, test for vulnerabilities in common business workflows before an API can be put into production. Pushing API security further left in the API development processes, using 3rd party and open source solutions to secure an API using the same testing infrastructure used to test contracts, integrations, and performance, but applied in service of applying the same level of security across API development teams. Augmenting developers with API security solutions that are designed, developed, and maintained by security professionals, but made available as simple, modular, executable Postman collections that can be manually run by developers as part of the development process, scheduled via monitors, or applied as security gates within existing CI/CD workflows.
Making Your APIs Observable
API observability is essential to moving teams forward in concert, increasing developer productivity while ensuring API quality. Most API observability focuses on the health and quality of APIs, ensuring they are providing what is intended for consumers—something the Postman platform has done since the beginning. However, the Postman API platform helps developers take this to the next level using the same collection—based solution for introducing observability into the infrastructure behind APIs. Postman collections can be defined as tests for APIs, as well as the infrastructure behind them, then scheduled for monitoring via monitors, which can then be piped into existing APM solutions like Datadog and New Relic. Offering developers a simple, low-cost, but effective way of introducing outputs across API operations that can be used to make the API lifecycle more observable. Allowing every individual part of the API factory floor to be monitored on a schedule and contributing to the overall observability that exists across teams.
Manage Multiple API Gateways
Postman has seen first-hand that we began moving into a multi API gateway world a few years back and has been responding with native API gateway integrations and platform operation collections that allow for the configuration, deployment, management, and automation of multiple API gateways. API gateways like AWS, Azure, Google, Kong, and Tyk all possess APIs for managing the operation of single or cluster of gateway instances, providing an opportunity for developers to more easily automate and orchestrate across the API lifecycle. Gateway integrations allow for the development and deployment of APIs to be kept in sync with the source of truth for each API that exists within an API workspace and synced to source control, and PlatformOps collections allow for much finer grain configuration, automation, and control over the deployment and evolution of each API. The enterprise landscapes within a single enterprise are likely to have multiple gateways in operation from top-down investment in SOA and API management gateways, bottom-up investment in more modern open-source and commercial API gateways, as well as the introduction of gateways via acquisitions. The Postman API platform is how you orchestrate and automate across all of these gateways, equipping developers with what they need to move forward in a must-gateway world.
Providing APIs for Your APIs
APIs have been a powerful force in making enterprise organizations more agile, nimble, and competitive when it comes to delivering desktop, web, mobile, and device applications. They have the same potential when it comes to APIs, leveraging the infrastructure we use to develop, deploy, and operate our APIs, to automate and orchestrate across the API lifecycle. The Postman API platform depends on the APIs for common infrastructure like source control, CI/CD, gateways, APM, and other enterprise solutions to lay the foundation of API operations, so it is natural for the Postman API platform to also have its own APIs. The Postman platform APIs provide programmatic access to your APIs and the API lifecycle around them. Literally, your APIs now have APIs, as well as your documentation, mock servers, tests, monitors, and other elements of API operations. This provides an unprecedented opportunity to configure, deploy, automate, and orchestrate how teams are developing and delivering APIs. Developers can use the APIs to do more with less, and automate away the work they find mundane, allowing them to focus on the business tasks that matter most to business operations. This is the year that developers realize their APIs have APIs and begin to take full advantage of what that offers as part of their work.
Automating Your APIs
The automation of API operations is the only way that developers will be able to keep up with the demand placed on them to deliver the applications and integrations needed to conduct business in a digital world. The postman API platform allows for the automation of the API lifecycle that produces APIs, but also the consumption of APIs as part of operations. The infrastructure behind APIs like source control, CI/CD, and gateways can be defined as Postman collections then automated using runners, monitors, and CI/CD pipelines. The internal and external 3rd party APIs can also be defined as collections, and automated using runners, monitors, and CI/CD pipelines. This platform capability allows for an unprecedented amount of control when it comes to automating the API lifecycle, allowing developers to augment what they do manually when it comes to the development of APIs. Again, helping them do more with less, and focus on the tasks that cannot be automated, but then streamlining the things that can. Once you also begin to take each of these collections used for automation and wire them up to existing APM solutions you end up with end to end observability across an automated factory floor.
Workflows Using APIs
Postman collections allow developers to construct simple or complex workflows using many internal, partner, and public 3rd party APIs to accomplish common operational and business tasks. Collections allow for not just each individual API request to be defined, but also the authentication, parameter values, bodies, and include data for specific business use cases as part of the workflows, going beyond what OpenAPI and other API artifacts can do. Collection defined workflows allow developers to define the business outcomes they are tasked with ensuring occur and define an entire suite of business capabilities that represent the business domain they operate in. If it can be done via an API, it can be defined as a collection, and if the series of API requests can be stitched together via web and mobile applications, it can be defined as a workflow collection—all without writing code. API workflows give developers the ability to better organize the common tasks around them, collecting many different API requests in a specific order, iterating across them, transforming requests, and handling any type of response using scripts. Putting another set of tools in the toolbox of developers, helping them take full potential of the APIs they are producing and consuming as part of their work.
Introduce to PlatformOps
As mentioned as part of other areas of this story, Postman collections can be used for not just regular APIs and microservices, but also the infrastructure behind them. Allowing developers to configure, automate, and evolve API operations—we call these PlatformOps collections. There are many different ways in which collections are used to document, test, and onboard developers with APIs, but PlatformOps collections allow for working with source control, CI/CD, gateways, APM, security, testing, and every other stop along the API lifecycle. PlatformOps allow developers to carve up the capabilities available via API infrastructure into modular, granular operational level capabilities that can be used to manually, or automate any aspect of our operations. This reality provides developers with a powerful way to look at API operations and take everything they know about producing and consuming APIs and apply it to the work they do each day. PlatformOps provide a compelling way to define and document each step of how developers deliver APIs and make it something that is repeatable and executable, allowing the process to be shared with their team, and easily handed off to new hires, helping stabilize the API Operations around us.
Report Across API Operations
Everything that happens on the Postman API platform is visible via team, workspace, and API reports. Providing the ability to not just understand what is happening with APIs, but also the teams are working on them, and the development that occurs within workspaces, which are synced with Git repositories. This provides an unprecedented level of reporting over what is happening across operations. Providing leadership, but also developers with a wealth of knowledge over how they are doing in comparison with other teams and groups. Reporting offers an ongoing, real-time view of API operations that allows you to the position where you are at in moving forward not just a single API, but how everything is working together in concert. Allowing APIs, teams, and operations to be governed, synchronized, and brought into alignment. Reporting is another way in which we can “see” API operations, and the digital transformation that is happening across the enterprise, providing us with a dashboard for understanding how everything works or doesn’t work.
Bring Your Teams Out of Shadows
There are 18M developers using Postman, a number that exponentially increases each year. Almost every enterprise organization we talked to has hundreds and in some cases thousands of developers who are using Postman to produce and consume APIs. The process of bringing developers underneath a single team, organized by groups to match enterprise domains, brings developers out of the shadows of operations and establishes a common area of team workspaces where they can collaborate. When developers work under a team account, they can still have personal workspaces that are only visible to them, but it introduces the ability to have shared team workspaces that are defined using role-based access control. RBAC-defined workspaces help keep everyone from stepping on each other’s toes, while still providing access to the APIs, documentation, tests, environments, tests, monitors, and other elements of the API lifecycle. The Postman platform becomes a common series of workspaces that are discoverable, and collaborative, which makes operations a much more known thing, and not just occurring on the desktops of individual developers.
Solving the Problems we Face
It is interesting to explore the problems Postman solves in this way. I like thinking of what we do in terms of solving problems and making developers’ worlds easier. I am often thinking of things in terms of specifically the platform and road map, or through the lens of the API lifecycle, and it helps me shift gears to think of it in terms of helping developers. It goes beyond just postman being an API client, testing, or producing APIs, and walks through the different ways in which the platform gets put to work as part of operations. While collections and OpenAPIs are mentioned quite a bit as part of this post, I don’t feel like I focused too much on the features of Postman, and it is more on exploring what I see developers doing with the platform. It was a lot more work to explore these twenty ways in which the platform enables developers than I anticipated, but I think it was worth it. It took me about 2 hours more than I anticipated, but it pushed me to consider the most valuable ways we’re making an impact on things this year.
Next, I think I am going to work at exploring how all this fits together as part of a strategy, and across the API lifecycle. I also want to continue highlighting how central workspaces, collections, and automation are to all of this. I don’t think people fully understand how game-changing API workspaces are to API operations. If you can’t find what you need across your operations and see what teams are doing, you are never going to be able to move things forward. A well-defined API platform that is carved up into logical workspaces, with a consistent approach to setting up workspaces will make developers feel more comfortable, help developers are more productive and drive collaboration and communication. I think it can help to hear about all of these ways in which the Postman API platform can help developers be more productive, but if you don’t know how all of this works together, it can be difficult to understand how to move forward in concert. I’ll get to work on defining this next, and then I’ll be ready to craft a more meaningful post for the Postman blog.