Postman
When I wanted to get a job doing REST API documentation, I showed the job description to a developer friend of mine and asked, “What do I need to do to get this job?”
I met most of the requirements already, but I had only done a tiny bit of API documentation, and what I had done wasn’t REST. He said I should learn to test examples in Postman and tell the hiring manager that my focus was on testing examples (because nobody would read anything except examples). I didn’t completely believe that, but I did agree that accurate examples were important. So I took his advice, learned to test examples in Postman, got the job, and never really used Postman much after that because I tested most of my examples with cURL for the next 3 years.
However, I got an email from Postman a few weeks ago about their New button. Documentation was part of the message. I honestly don’t know if it was always possible to do documentation with Postman, but now it is. So let’s take a look at Postman for API documentation.
Since I’m a writer, you might assume that I’d start by reading the instructions. I’m not going to though. I’m going to try it out first and then read when I get stuck :)
I use the Chrome app for Postman. Assuming that you have a Google account and you’re logged into it, you can add it to your Chrome apps (just like Gmail and YouTube) and launch it as follows:
1. Go the Chrome web store and search for Postman (here’s a link to ease the search: https://chrome.google.com/webstore/search/postman).
2. Find the Developer Tools app, and click the + Add to Chrome button.
3. From the chrome://apps/ click Postman.
When Postman launches, the Create New window appears automatically. However, closing the window and clicking the New button shows the same options. We’ll get to the New button and the documentation soon, but first let’s assume that we’re starting with an existing collection. As the API documentation writer, I’ve always started from the JSON schemas.
To start with an existing collection, you’ll want to find a public JSON API for use in web development, such as http://developer.wordnik.com/v4/words.json. Import the collection as follows:
1. Close the pop-up window.
2. Click the Import button at the top of the page.
a. Click Paste Raw Text.
b. Copy and paste the raw text from the public JSON file.
c. Click the Import button.
Now we’re ready to create new documentation as follows:
1. Click the New button in the upper-left corner.
2. Click Documentation.
3. Click My Collections.
a. Select the name of the collection to document (mine is currently called “Postman Barebones”).
b. Click the Create button.
c. Click Close.
The auto-generated documentation has been created on the right-hand side. Edit it as follows:
1. Hover over the auto-generated docs.
2. Click the Edit icon.
3. Update the placeholder text with the actual information that you’ve gathered from product owners, subject matter experts, and your own testing.
4. Click the View in web button to see what it will look like when published.
So far, so good. I like it. I don’t know why I have two introductions in my table of contents, but that’ll take further investigation. Of course, in real life, I’d also have to add/test examples and edit any descriptions or parameters for searchWords, getWordOfTheDay, etc. I’ll save that for another day.
Also, why are all my screen shots above centered? Something about Medium that I’ll have to figure out another day as well.
Happy Thanksgiving!