In my world API definitions are more valuable than code. Code is regularly thrown away and rewritten. API definitions hold the persistent detail of what an API delivers, and contain all of the proprietary value when they are properly matured. OpenAPI has definitely risen to the top when it comes to which API definition formats you should be using, however, Postman Collections have one critical ingredient that makes them ultimately more usable, sharable, and meaningful to developers—-environmental context. This small but important difference is what makes Postman Collections so valuable as a single quantifiable, shareable, executable unit of representation for any digital capability.
Like OpenAPI, Postman Collections describe the surface area of a web API, but they have that added layer to describe the environment you are running in, which makes it much more of a run-time and execute-time experience. This may seem like a minor detail, but developers who want instant gratification, a Postman Collection bundled with the Postman API lifecycle tooling, makes for a pretty powerful representation of a company’s, organization’s, institutions’s, or government agency’s digital capability. Allowing for API providers (or consumers) to describe what an API does in a machine readable format, bundle with it the environment context to actually execute the digital capability, and enable the unit of value to be realized within the Postman API development ecosystem.
I can take any of my internal, or 3rd party public APIs I depend on, make successful calls to them, including authentication, tokens, and other environment variables, then export as a portable Postman Collection, and share with anyone I want using a simple URL, or by embedded the Run in Postman button within documentation, blog posts, and other resources. Then, any potential consumer can take that Postman Collection, load into their Postman client, and be able to realize the same digital capability I was using—-no documentation, on-boarding, or other friction required. You get instant gratification regarding putting the digital capability to work, exactly as I intended. This quantifiable, shareable, and executable nature of Postman Collections is what elevates them to a position held by no other API definition format out there.
It is this dance between machine readable API definition, and API lifecycle tooling (client, documentation, testing, mocking, etc.), linked together with the environment context that continues to ensure Postman captures my attention. Ensuring the technical details of your API is captured in a machine readable format is something I don’t think all API providers fully comprehend. Enabling developers to put an API to work for them in a single click, instead of the usual on-boarding dance, digestion of documentation, selection of relevant programming language SDK, and other cognitive load associated with API integration—-is critical! APIs represent the digital capabilities of your company, organization, institution, or government agency—-Postman Collections are how you ensure your capabilities are quantified, shared, and executed by internal and 3rd party developers.
Disclosure: Postman is an API Evangelist sponsor.
