Postman Part II

Perfect timing! Last week, I wrote about trying out the Postman Chrome app for documentation. This week, I got an email from Postman about Google deprecating all the Chrome apps. So now I might as well talk about using the native Postman app in testing APIs for documentation purposes.

Get the native Postman app from https://www.getpostman.com/apps. Follow the instructions there for downloading and installing.

To use Postman for testing… the way it usually goes is that you need a username, password, and a developer key. Once you have these, you’ll typically want to find an endpoint with the word “auth” or “authenticate” or the equivalent. From the request to the auth endpoint, you’ll receive a response with a token or similar that you’ll use in the requests that follow.

For this test, I’m going to use Wordnik again. Get a username, password, and key at wordnik as follows:

1. Sign up at http://www.wordnik.com/signup

2. Use your wordnik username from step 1 to get an API key at http://developer.wordnik.com/

3. Find the info about the developer key in your email inbox 24 hours later

To set up Postman for the test, use the raw text or the link at http://developer.wordnik.com/v4/account.json to import the “account” collection into Postman as described last week. The native app looks just like the Chrome app, so all is well.

Keep in mind that when I imported the collection, I couldn’t immediately tell exactly how to use it in Postman. I had to look at the existing documentation as well as the raw text. Such is the life of the writer. It’s a very real-world scenario. Don’t beat yourself up about it. Sometimes the json syntax is accidentally incorrect, sometimes it’s valid json but the format is better written for a different tool, sometimes the doc tool is homegrown and the person who built it is gone and nobody really knows anymore what the format should be to make it look quite right. That’s why you have to discuss with SMEs, try it out, and write it down.

In Postman, I’ve changed the name of the account collection to “Dictionary Auth” for my own purposes. Under authenticate, enter your credentials as follows:

1. Change the format placeholder in the URL to json

2. Click the Params button

3. Enter a confirmed Wordnik username in the username value field

4. Enter the corresponding password in the password value field

5. Add the api_key parameter and enter the developer key in the api_key value field

Notice how the request URL changes to match the values entered:

Note: don’t save your own username, password, or api key if you plan to share or export your collections.

When you press the Send button, you’ll receive a response:

This response is good, so your test is almost complete. You’ll use these parameters in the requests that come next. However, that sounds like something to save for another day :)

If you were the writer and docs didn’t exist, you’d update the authenticate description in Postman (as described last week) with what you just learned from this testing and from looking at the raw text you imported.

Then if you click the the Code link, you can auto-generate code snippets based on your successful request:

You can modify or use the code snippet as-is for your doc examples:

Then you can click the View in web button to see what it will look like when published. Keep in mind that I haven’t actually spoken with anybody and I haven’t finished:

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.