THE CURIOUS DEVELOPER

Postman is a very powerful application to have in your toolbox while developing REST interfaces. Postman lets you very easily run HTTP verbs such as GET, POST, PUT and DELETE against your API.

It is very easy to get started with Postman after the simple basic installation you can within seconds start firing requests. However, Postman also has many features which more advanced users love. In this article, we are first going to give you quick instructions on how to send basic requests and after that, we will dive into some more advanced features that I, personally, use every day.

Sending your first request with Postman

Create a new tab and select what HTTP verb you want to perform, enter the request URL. If you are performing a POST, DELETE or PUT you will most likely want to add a body to your request as well. So simply select Body. Select what type of data you want to send, if you are looking to send JSON or XML, then select raw and switch Text to one of them.

After that, you should be good to go. We can use the REST API that https://jsonplaceholder.typicode.com provides which simulates a REST API. You can send all the HTTP verbs, and it fakes it happening by replying with an appropriate response.

Collections

So, you’ve started setting up requests that can be sent to your REST API. Wouldn’t it be convenient if we could save them? With collections, you can. With collections, you can create folders of requests (or other folders). Simply save your request and select which collection that you want to save it to.

Collections are also a very convenient to use when you are looking to automate more of your tests. Pressing the arrow on the side of the collection will cause a new menu to pop up, where you can select Run.

Pressing Run will open the Collection Runner window. Where you can select a Collection to run, an Environment which will make more sense a bit later in the tutorial when we go through that. You can also select how many times it should run by changing the iterations. If you for some reason need a delay between each request then you can also update that. But as the collection is running synchronized, meaning that it won’t run the next request until the one before was finished, you probably won’t need to use that. You can also select if you want the responses to be logged which is probably a good idea for debugging purposes.

You won’t need to do anything with Data and Persist Variables, just leave it at default.

Running the collection will run all the requests that are in your collection from the top to the bottom, meaning that requests that you want to run first, you will want to have at the top in the collection.

Later on, we will add more meaning for running collections after that we added tests to verify responses.

Authentication

Many APIs aren’t open for anyone to use, and therefore requires some sort of authentication. Postman supports many different types of authentication, for example, Basic Authentication, OAuth1, OAuth2 and Bearer Token.

Simply navigate to the Authentication tab on the request and select Basic Auth and enter the information. In more recent versions of Postman it is possible to have a default authentication for all the requests in the collection, but of course, you can override authentication on requests as needed.

Environments

Environments are my favorite feature of Postman. If you press on the eye in the top right corner it gives you the option to create an environment.

It is important to know the difference between environments and global variables. Variables saved in an environment is scoped to the environment only and won’t be reached outside it. Global variables can be reached in any environment.

A perfect use case for the environment is if you have a separate development environment of servers and a different one for staging. Then you can create a development environment and a staging environment.

The variables that you create in the environments can be used in your requests. For example, let’s say your URL to the development environment is localhost, but the staging environment is located at staging-url.com. Let’s then create a variable called URL in both the staging and the development environment that you created.

We can then modify the URL in the request in our collection to {{url}}/api/… as an example. So when using the staging environment the requests will go to staging-url.com, but if we quickly change the environment the same collection will send the requests to localhost.

You can save almost anything as environment variables, another good use of it is saving API keys and authentication tokens. In the next chapter where we go through tests, we will also learn another useful thing it can be used for.

Tests

Navigating to the Tests tab will give us the options to write tests. Tests in Postman are written in JavaScript and are run after the response has been received. So, because it supports JavaScript you can actually write some quite advanced tests.

Postman also provides us with many convenient methods to verify responses.

pm.test("Status code is 200", function() {
   pm.response.to.have.status(200); 
});

With the snippet above, we create a test named Status code is 200, that will verify that the response has the status 200.

For more examples of what is possible to do, I recommend checking out the Sandbox API reference.

It is also possible to possible to save data from tests into environment (and global) variables. Let’s say that we have a REST API that makes it possible to query for a license plate number of a car and you get a response with who is registered as the owner of the car. In Sweden, we have something referred to as a personal identification number. Every person has a unique number, where the first part of it is your birthday, and then 4 secret numbers at the end.

{
  "personalIdNumber": "931026xxxx"
}

Let’s say that we want to use this personalIdNumber for the following request, so let’s save it into an environment variable. First, create an environment variable where we will be storing it. Then we add the following code to the tests for storing it.

var jsonData = JSON.parse(responseBody);
postman.setEnvironmentVariable("personalIdNumber", jsonData.personalIdNumber);

We can now use the variable in future requests. For example: GET {{url}}/api/person/{{personalIdNumber}}.

{
  "name" : "Viktor Plane",
  "age" : 24,
  ...
}

We can also use the tests section in a previous request to generate some sort of variable that should be used in a request.

Final words

Postman is a truly a powerful tool for developing and testing REST APIs. There are very few limitations, and personally, it is probably my favorite tool that I use every day in both my hobby projects and at work. As you get more comfortable with Postman you will notice how it can replace a lot of manual testing. It is even possible to export collections and environments and run them with Newman which is a command-line collection runner for Postman so that you take the automation to the next level. But I am purposefully leaving that out of this article as the scope would grow too big. However, I recommend checking Newman out when you wanna take the automation to the next level.