Welcome to 2020!

Postman is an immensely useful tool for working with, documenting and testing APIs.

Collections

Firstly, it is advisable to setup a collection when creating your API calls in Postman. These can be managed in folders, so that you can group them in any way that makes sense to you. This enables you to group together all your various projects API calls together so it all makes sense. Rather than having all kinds of disparate API calls flooding your Postman interface. Furthermore, you can run tests automatically in batches in collections and against environments.

Variables

Here's a tip - never hardcode the url for your API! The smart thing to do is to use environment variables.

• In the Postman URL bar, enter your url as follows: {{url}}/todos

{{url}} is the name of your environment variable. This lets you update urls if necessary without having to manually go and make changes through your entire collection.

Similarly, you can use environment variables for other things. For example:

If you have a collection of API calls, you can capture the ID in the response to a POST request, and then set that ID as the value of an environment variable which you can subsequently use in follow-up calls in your collection. For example to run a GET request to an endpoint i.e. /todos/{{id_goes_here}}

This is immensely useful when running tests on your collections. Speaking of which, yes, you can write automated tests for your API calls in JavaScript!

Tests

One incredibly useful feature of Postman is that you can write automated JavaScript tests. What does this JavaScript look like you might ask?

In the "Tests" tab of your API view:

// check for a 201 response code
pm.test("response status code is 201", function () {
    pm.response.to.have.status(201);
});

// check for specific field values
pm.test("response contains a user with id, email and active fields", function () {
    var jsonData = pm.response.json();
    pm.expect(jsonData).to.be.an('object');
    pm.expect(jsonData.id).to.be.a('number');
    pm.expect(jsonData.email).to.be.a('string');
    pm.expect(jsonData.email).to.contain('@');
    pm.expect(jsonData.email).to.contain('.');
    pm.expect(jsonData.active).to.be.a('boolean');
})

// setup environment variable to be used by other API calls
var jsonData = JSON.parse(responseBody);
postman.setEnvironmentVariable("user_id", jsonData.user.id);

From here, this enables you to setup any subsequent API calls in your collection or test run that rely on this particular ID to get passed through in the URL bar as follows:

• {{url}}/users/{{user_id}}

Pre-Request Scripts

Similarly, you can do various things "pre-flight" to the API call which can be useful. For example, if you have a collection that creates users with unique email addresses, hardcoding the same email address might not be ideal for multiple runs. As such, in the "Pre-request" tab of your API call window, you can do something like this. Using an imaginary POST to /users:

const {Property} = require('postman-collection');
let randomWord = Property.replaceSubstitutions("{{$randomWord}}");

// use Postman dyanmic variable $randomWord
var email_address = randomWord + "@domain.com";

// JSON.stringify will serialize the object so that Postman can save it
pm.environment.set('user_email', JSON.stringify(email_address));```

What the above will do, is enable you to do the following in your the JSON body of your POST request. Which is great because now you don't have to hardcode any silly email addresses like "test@test.com":

{
    "email": {{user_email}}
}

Note: Another very useful feature is dynamic variables (as used above). You can find out more about Postman's dynamic variables here

Another note: Apparently, Postman uses the faker library beneath its dynamic variables if you were wondering...

Conclusion

Taking the approach above, enables you to setup a collection of API calls with dynamic and environment variables that can change dynamically. This alleviates the need to repetitively and manually run API calls to check for correct behaviours. Granted, there may be overlap with your API unit and integration tests, but to be honest, I find Postman very easy to work with and quite intuitive - at worst, its a few hours extra work that enables you to quickly and easily setup and share API calls. At best, it is another layer testing and documentation on top of the rest of your testing and documentation! ;)

PS. Another quick tip is to save examples of API posts and responses for documentation purposes. This lets other developers in your team see what API requests and responses are supposed to look like when working correctly.