How We Build Learning Experiences Inside Postman

Sue Smith

March 22, 2021· 6 mins

Learning about APIs is hard, whether you’re trying to get yourself up and running with a specific API or just want to get to grips with the basics of what APIs are and how they work. Those of us who are in the business of technology education are always looking for ways to break the barriers people face when they’re trying to be successful and informed with tech. In this blog post, I’d like to share some history and detail on what we’ve been calling “Learn by API” at Postman—a framework we’re hoping will help enable a broad range of people with API learning at scale.

In early 2020, I was working on documentation for Postman and was trying to get decent screengrabs to show some aspect of an API request. We typically use Postman Echo for this, a service that just sends you back what you sent it (it’s pretty handy for messing around with request configurations without worrying about breaking anything). I really wanted images that looked more like “real” APIs, and so I started using Glitch to quickly throw together APIs that would return whatever I wanted—and that would be super quick to set up and tweak as I went along.

It gets a bit Clippy

It occurred to me that since I was building a new API, I could actually structure it specifically for learning, and even include instructional information in the response body. Okay, so sometimes my desire to insert myself between the learner and the tech gets a bit, well, Clippy.

I tried including learning info in a response property like metadata, but soon felt it wasn’t the most readable or beginner-friendly experience, and even worse that it could confuse the learner. This is where the Postman Visualizer came in: By adding a template to your request tests, you can build response data into visualizations such as charts and graphs—pretty much anything you could do in a web page. By combining an API built for learning with a visualization turning the response into a tutorial, we had the beginnings of a new way to teach people about APIs, all in context inside Postman.

Initially, I just released a few templates via the Postman API Network. These were meant for people to import and walk through instructional steps, explore requests and responses, and learn API literacy fundamentals (like methods, addresses, paths, parameters, authorization, status codes, body data, and response structures in JSON).

Student training as education R&D

One of the projects I work on at Postman is our student program, where we partner with students and educators in various types of institutions to teach APIs. An early goal for the program was to award certification as part of an engagement pathway—from Postman Student Expert to Leader, where students would drive learning in their own colleges and communities. We did an initial pilot training with the first students who had registered interest in the program and then built out a more comprehensive version of the learning collection to support it. Here’s how the training works:

• Learners import a collection into Postman and send the first request
• The responses guide the learner through next steps at their own pace
• Each step instructs the learner to complete the requests in the collection, adding configurations, requests, and other components, including test scripts
• A final section requires the learner to reapply what they learned independently in a slightly different context
• A last request checks the learner’s collection for completeness, allowing them to track their own progress and action any missing elements
• When everything looks good, the learner submits their collection to receive the badge

A few Postman quirks are involved in making this all work, including using the collection’s public link, which returns a JSON representation of the collection that the final request tests script analyzes to check for the required elements and writes out any missing parts in the test results. The Student Expert collection also uses a Glitch API and a mock API built using Postman examples. On the submissions end of the process, we use collection runs to validate learner submissions.

By using this experimental collection in conjunction with live training sessions, we were able to test, validate, and gather initial feedback, then make the collection generally available to anyone who wanted to use it. When users successfully completed trainings, we awarded Open Badges using the Badgr platform, and Discourse badges for the Postman community forum.  We were pleasantly surprised to find that lots of people started sharing these on LinkedIn, and that a significant portion of the recipients were not actually students but experienced professionals working in the industry. Within the Postman company, we’ve even started to incorporate the trainings into employee onboarding for various teams.

Postman Galaxy and beyond

Building on the success of the student expert training resources, we decided to use the Learn by API approach for the training sessions at the Postman Galaxy conference in February 2021. We wanted to generate assets that we could continue to draw on going forward, and that would leverage automation to enable people en masse. In the time since the initial student training developments, the Postman platform has also introduced public workspaces, which allowed us to take this bespoke learning experience to another level.

The new public workspace for API trainings within Postman includes resources for learning a few core topics, including APIs 101, API Adoption, Testing and Automation, and API First workflows—all found here.

We used a few variations on the original Learn by API model and hit a few barriers along the way; we still have a lot to figure out about teaching people API literacy, but by continuing to develop this in conjunction with partners, customers, and community, it’s shaping up to be a tool for enablement around APIs at scale. Here’s a rundown of what we built for the Postman Galaxy educational trainings:

• A public workspace
• Two APIs built for learning (hosted on Glitch, with backups on Heroku)
• Three learning collections (with documentation, visualizer scripts, progress tracking scripts)
• Two mock servers returning training data
• Backend collection processing by API (we also experimented with Newman as a library and the Postman Collections SDK)
• A specification with steps in the Postman API Builder overview and in the spec description field (which makes them populate in collection docs)
• Several more badges
• GitHub repos for contributions
• Submission processing collections and monitors

Remix!

Although this learning experience is primarily delivered inside Postman, every component in the Learn by API framework is remixable, extensible, and available to anyone who wants to create a customizable learning pathway. The core goal was to create an open, flexible model that people outside the Postman company could also use and contribute to.

Further enhancements we hope to develop include an API specification defining the structures that the standard Learn by API visualizer script will be able to render as a tutorial, use of the Postman API for more robust submissions processing, and additional automation on the backend including integrating with APIs for badging and learner communication.

If you’re interested in getting involved in this API learning model or have any feedback, please let us know. Tell us in a comment below or through our Community forum and GitHub repository.