I am going through a bunch of different tutorials from API providers looking to motivate users to accomplish some fundamental API on-boarding task, or introduce them to some meaningful workflow involving their API. I am amazed at how much detail, including screenshots that people go into, and how so few of them actually provide Postman collections that help power the task or workflow they are shining a light on. I’m determined to figure out why. I’m guessing folks are used to using Postman as a simple web API client, and haven’t really fully grasped the concept of sharing collections, and how collections go above and beyond what they are used to with Swagger / OpenAPI. After over eight years of people using Swagger / OpenAPI, most still think it is a documentation solution, so I’m not really surprised that folks don’t fully get collections—I didn’t until recently.
The one thing I want to help people understand is that your Postman collection should be the tutorial. It is fine to have all the content and screenshot fluff around it, as this helps you with SEO, discovery, and other things, but everything you describe int he tutorial should be actionable in your Postman collection—this is the purpose behind collections! Postman collections excel at containing all of the detail you need to walk folks through making API calls in a portable, shareable, executable unit of representation for your API. Making it so that your audience can take the tutorial with them, play with it in their own environment, and the best thing is that it stays around in their application development environment until they remove it, providing a potentially ongoing reference for them at some point in the future—making your tutorials stickier.
It takes experience to be able to craft a meaningful Postman collection, going beyond just a basic reference of your API. It isn’t something I”m very good at yet, but will spend time honing and polishing. As I get better at it I will help share stories about the process, and gather more tips for how API providers can get better at publishing their own tutorials. It can be difficult to understand what is possible with API definitions, and I know that Postman collections has a lot of nuances that seem to escape us. I know that I didn’t fully understand how it was different from OpenAPI, and I was just seeing the platform evolve towards testing, mocking, and documentation. Which is needed, but I really think that collections for on-boarding developers and non-developers to a new API, to new concepts, and help them learn how to be more efficient at putting APIs to work is where the future lies with Postman. I believe in Postman as a full API lifecycle tool, but I also believe in it as an essential tool for on-boarding people to APIs.
If you are crafting a tutorial for your API make sure you include a reference collection for the APIs you are talking about—as a minimum. Every tutorial should have a Run in Postman button associated with it. If you tell developers to use Postman, you should enable this with a collection. If you are posting screenshots of how to use your API in Postman, you should enable this with a collection. If you are wanting to get really slick with how you craft your tutorials, then seamlessly dovetail them a Postman collection and make sure your API tutorial is something that encourages your target audience to go from reading to making calls to your API within a couple of clicks. Helping ensure that your tutorial isn’t read then forgotten and ensure it becomes something that your API consumers can get hands on with, and if you are really lucky the developer will leave your collection in their personal or team Postman space and continue to make use of in the future-taking your API tutorials to a whole new level by transforming them into a Postman collection.
