I have been using Postman collections for a couple of years now. I have been auto-generating them from my central database alongside OpenAPI 3.0, and previously Swagger 2.0, as part of my regular work profiling APIs. I have imported and used many different collection in my Postman API development environment. I assumed I fully grasped what they are all about. I mean I am the API Evangelist, all I need to do is play with something a little bit, and the API utility of it will become evident to me within minutes. I know my stuff. Right? Not exactly. Apparently I was pretty tainted from my usage, adoption, and evangelism of OpenAPI, and I didn’t fully see how Postman collections can be used to define APIs, and act as an executable unit of representation for an API.
Postman collections define the surface area of a API just like OpenAPI. I fully understood this. I also grasped that it went beyond OpenAPI in acting as more of executable representation of an API. Meaning you can populate parameter values, and use variables as part of Postman environments, creating and versioning different collections for the same API, allowing it to be executed in a variety of scenarios. What I didn’t get was how you can label and organize different scenarios and workflows into different folders, and how pre-execution, tests, and monitors can be applied against collections, folders, and that there is different levels of variable and script scoping dependent on how you structure your collections. I know us pundits like to call OpenAPI definitions API contracts, but they are void of the dynamic variables, environment, testing, and monitoring that is required to truly be a contract--this isn't so with Postman collections.
I have been increasingly excited about the executable potential of Postman collections over OpenAPI’s static nature. Sure, it can be used for making actual API requests, but it doesn’t have all the nuts and bolts of making that request like Postman has. Postman environments, variables, and being able to define a variety of collections for the same API provides a pretty seismic shift in how we deliver our API definitions. It means I can hand someone an API definition, and they can execute in in exactly he context I hand it to them. I’ve long augmented OpenAPI with other definitions to mimic this behavior, but Postman provides version control, workspaces, and other essential elements that make this functionality occur by default, not as augmented behavior--helping you manage the process all along the way. This was already a game changer, but it is just the beginning of the potential in my opinion when it comes the potential of Postman collections.
When defining Postman collections I can fully define the surface area of an API. I can also define some, or all of the contexts in which that API can be run. Populating parameters and other details as part of the collection or environment settings. This is just the start. You can also then define pre-request scripts to manipulate all of those parameters and variables, and you can then run tests after requests are run, setup monitors to ensure the tests are satisfied in an ongoing basis. This elevates API definitions to the level of API contract for me. It provides the core of each API contract, all of the contexts for what the API contract covers, and the ongoing validation of the contract in question. This is significant. With all of this, you can also provide a mock of the contract that anyone with access to the API collection via a Postman workspace can put to work understanding all of the details of the contract in question.
I am a little embarrassed that I didn’t see all of these details, as well as the potential and scope of Postman collection folders. I didn’t see that collection folders introduce scope layers which can impact how environments are applied, and how scripts and tests are executed. While I am embarrassed, I’m also fully aware how we can all easily get siloed into how we think. We can easily become captured by the tools, services, and practices we already know, and become very biased when it comes to being exposed to new services, tools, and practices. I am going to take this to heart and spend more time reassessing other tools and services I’ve been playing around with and may have put back on the shelf thinking I understood everything that was going on. This is one aspect of the API space I enjoy regularly, that I can keep learning after so many years, and realize how little I actually know about what is happening with APIs, and I can easily break into new territory with just simple shifts in how I view the landscape.
