I am amazed at the number of blog posts I come across for API providers explaining how their API consumers can use Postman with their API, but do not actually share a complete Postman collection for developers to use. API providers obviously see Postman as a tool for making API calls, but do not fully grasp the ability to document an API with a Postman collection, save, publish, and share this collection with documentation or the Run in Postman button. As part of this realization I am not looking to shame API providers for not understanding what is possible, I am more looking to acknowledge how much work we (Postman) have to to when it comes to helping folks understand what is possible with the Postman platform, moving folks being the notion that Postman is just an HTTP client.
There are some pretty involved tutorials out there for using Postman with a variety of APIs. API providers have invested a lot into these blog posts, tutorials, and other resources to help their API consumers on-board with their APIs, but do not publish Postman collections as part of their documentation or tutorial. This tells me that API providers aren’t seeing the portability and share-ability of Postman collections. They simply see Postman as an API client, not as tooling for defining, sharing, publishing, versioning, saving, organizing, and evolving API requests. This means we have a lot of work ahead of us to educate folks about what Postman collections are, and how they will make your life easier, while reducing redundancy across operations. Helping folks move beyond simply operating Postman as an isolated HTTP client.
Having full control over defining a request to an API while being able to see the details of that response is the core value of Postman. Developers get it. Clearly they also see the need in sharing this ability, and equip others realize the same value. They are crafting tutorials and blog posts to help folks understand what is possible if they use Postman, but they don’t go that extra step to use Postman documentation and Run in Postman button as a quick way to move people from learning about what an API does to experiencing what that API does. The share feature within Postman is pretty prominent, but I think the concepts why and when you’d share with another workspace, via a button, or simply a link gets lost on most folks. I’m thinking we need hundreds of examples of this in the wild—every time I see an API provider publish their Run in Postman button I am going to Tweet out the fact that they are using Postman in this way.
I am looking to help existing Postman users see a collection as more than a folder structure for saving API requests within their local Postman. I want to help them realize that a default characteristic of a Postman collections is that it can be shared into workspaces, within documentation via the Run in Postman button, and within any API narrative simply using a Postman link. I want to help folks understand that being able to have full control over an API request as well as the response is the fundamental value of using Postman, but the portability of your collections is how you exponentially extend that value to your co-workers, community, and other stakeholders in your API journey. Every API should have documentation, but every API should also have one or more Postman collections available for enabling anyone to put that API to work within one click. We have a lot of work ahead of us to highlight all the ways in which folks are using collections, and expand the awareness of users who haven’t broke free of their isolated usage Postman, helping them make sure there is always a Postman collection available when publishing your docs, tutorials, or other API stories.
