Postman – a beacon of hope in a world of API darkness

Joyce

June 22, 2018

When you’re lying in bed and ready to sleep, do you wish someone would turn out the lights? Maybe you’re fancy, and say “Ok, Google” or clap your hands. For the rest of us, something that we all have by our bedside is Postman.

Let’s see how you can turn off your lights with Postman.

I’m using the Nanoleaf light panels. You could also try something similar with a smart light bulb accessible through an HTTP API, or roll your own with an Arduino server and addressable LEDs.

A slow start

First things first, I didn’t want to build my own app. I intended to use Postman as the HTTP client to tinker with the light panels. A lot of folks use Postman like this, to poke at something to see how it works. I planned to use Postman to spin up a quick proof of concept, and if that worked out, I might do something more.

Now I’m not a hardware or IOT expert, and only know the basics of local networking. And so, I spent the better part of a weekend trudging through various smart device forums and sifting through the Nanoleaf developer documentation just to get started.

During that weekend of drudgery, I came across a number of developers in the forums who were using Postman to try out their requests. I wished with all my might that someone had already created a Postman collection to help me get started more easily, but that was not the case.

Fortunately, Charlie was there to provide some moral support.

Using Postman to send API requests

When I finally got started, I browsed some of the requests documented on the Nanoleaf developer portal (requires sign in). I copied one of the requests from the Nanoleaf portal, pasted it into the Postman app, sent the request, and inspected the response. This was great, but I wanted to try out more!

It was really tedious copying and pasting everything into Postman. My OCD quickly kicked in… and before I knew it, I documented the entire Nanoleaf API as a Postman collection.

A Postman collection is a great way to organize your thoughts and communicate with other people about an API. At Postman, we say a collection is an executable description of an API because you can import the collection into your local instance of the Postman app and start interacting with the API right away.

I dreamed about all the sweet karma I would get from these grateful developers for creating a Postman collection, or at least I could save them from the frustration I encountered ?

Document those APIs!

Besides just creating the actual Postman collection, there’s a bunch of other stuff you can do inside the collection to help document the API.

• Add a Quickstart folder containing a series of requests as an example use case. 
• Jot down descriptions in markdown to the collection, folders, requests, and parameters to explain each in deeper detail and outline required variables.
• Use these descriptions to introduce the required and optional steps, explain new concepts, and communicate other important things to your users.
• Save example responses for each request so that if you’re offline, you can still see what the response should look like.

As my energy started flagging, I published my documentation with a final 2 clicks. And lastly, I created a Postman collection template so other developers could use benefit from my hard work and search for this collection from inside the Postman app.

Check out the Nanoleaf collection documnetation, and perhaps you’ll find it illuminating too ?

Further Study

I wanted to the sequence of Quickstart requests to mirror a new user’s typical workflow, and so I decided to add some basic scripts using postman.setNextRequest to the requests to create some branching logic if someone wanted to run the entire Quickstart folder using the Postman Collection Runner.

The last thing I added was a few test scripts and log statements to catch any errors and give me more visibility into what was going on.

Next on my list, I might build out some other simple workflows with tests and scripts. For example, if I wanted to be notified every time a new team signs up for Postman, I could add a webhook to the Stripe API to light up the Nanoleaf in the Postman office. I could even pull the new team’s organization colors and update the effect that displays on the Nanoleaf. The possibilities are endless!