I had generated a Postman Collection for the Fast Healthcare Interoperability Resources (FHIR) the other day. Making a simple, easy to use, executable representation of any FHIR compliant API. I wanted to get intimate with the healthcare API standard so that I can better contribute specification and conversation, but I also wanted to use the specification to map out what industry level API contracts can be using Postman. Over time the Postman collection will evolve, and become more robust to contain the pieces of the puzzle that help move it from being an API definition to an API contract.
After creating the collection I have now published my FHIR API Postman Collection as documentation and to the Postman API Network. It still has to go through a review process before it is available in the Postman Network, but you can get at the documentation and Postman Collection directly. The process demonstrates how you can go from a working Postman Collection to documentation and discovery in just a couple of clicks. Then make your API collection and documentation available to any developers, helping them go from discovery to making actual API calls in just a couple clicks. The process for me demonstrates how ALL APIs should be defined, ensuring all APIs are well documented and executable by default—not something developed have to figure out for themselves.
I am still working on which of my API definitions I want to be publishing to the Postman API Network. I’ll be working to convert all of my API definitions to Postman Collections, and publishing API documentation, but I’ll be very selective about which ones I publish to the Postman API Network. I really want the API provider to take charge of this process. I’m happy to have all these APIs associated with my account, but it would be more authoritative to have Postman collections, documentation, and the directory page managed by the API provider themself. It doesn’t take much to manage your Postman Collection, and something within the power of each API provider. I’m happy to even do some of the heavy lifting in creation of the Postman Collection, but that last mile is really the low bar for what I can expect from API providers.
The trick is to get the attention of API providers and helping them understand the value of having their API defined as a Postman Collection in the first place, as well has taking a moment to see how it is literally a couple of clicks to go from collection to documentation and directory listing. I’ll keep tackling this problem API by API, company by company, and writing stories about each time I go through this process. I find that the savvy API providers eventually reach out after I publish information about them. One signal I track and add to their overall API rating, helping me understand the API providers who are actually somewhat aware of what is happening around their API, versus the ones who don’t really care. Helping me understand the overall presence of each API provider, and how much they are paying attention to the world around them, and ultimately care about their API community.
