Postman collections
An open letter to API developers
Dear API developer,
Let me first thank you for making the decision to offer your data for me to consume. In a time where many companies are holding on to their data as tightly as they can, it is commendable that your company is forward-thinking enough to realize that the world is better when we can share information and grow together.
Depending on your industry, and whether the data being offered was the core offering of your organization or the by-product of another process, I realize that it can be quite the fight to convince senior leadership that the data being offered is more valuable when it is made (semi-)public. I’m sure you had to sit through many boring meetings while extolling the virtues of sharing vs. hoarding, time which could have been better spent doing almost anything else.
You have gone through plenty of testing, ensuring that the data from your API is being returned correctly, that it is formatted logically, and that it is hopefully highly-available. You have fed it countless variations of request values, and confirmed that the responses match what is expected. And you probably did at least some – if not a majority – with Postman.
Why, then, are you making your customers rebuild their own Postman collection instead of just sharing the one you and your team have built? Not only does it save time on your consumer’s side, it ensures that as you update your API, they will immediately have the most up-to-date version of what a correctly formatted request looks like, rather than having to dig through some esoteric documentation that shows that a request must now be submitted in all lowercase, or must have the JSON body in a correct order. Even if it’s not to JSON API spec, I can quickly compare my request to yours and see my problem right away, saving me a call to you or your support team.
My personal suggestion is to add the cost of your Postman Pro licenses and maintenance of the collection to the monthly subscription costs your customer is paying for, but the financial decisions are ultimately up to you. All I ask is that you give me a way to immediately import your API definition to my Postman instance, and keep it up to date over the lifetime of our relationship.
If I can get up and running quickly, that is worth much much more to me, than having a few extra fields that I may or may not ever use. It will make me much more likely to obtain and retain your services, even if it’s not otherwise as fully-featured as your competitor.
With my jaw mostly unclenched,
nexxai