Postman Premier - The Minimal Postman you need to Learn
Tags: postman, apitesting
Published: 2023-02-13 15:32:27

## Introduction

Welcome to my Fullstack with Santosh. Today we are going to learn about how to use Postman as a backend engineer to make our daily life easier. Postman is an API testing tool where you can test your REST APIs. It has now developed into handling many different kinds of interfaces, but today we are going to focus on the REST APIs.

Make sure you have Postman already installed. I work on Ubuntu and the way I install is `sudo snap install postman`. You can find instructions about your platform on the downloads page: <https://www.postman.com/downloads/>

When you open Postman for the first time, you might see a screen similar to this:

<img src="https://d2kbulfv42d43j.cloudfront.net/2022/Q4/postman-home-screen.png" caption="Postman home screen" alt="Postman home screen" position="center" />

Your home screen might appear a little different because 1. I have already signed in. 2. I have already created some workspaces. 3. I have changed the theme to dark.

## Create a collection

Before you even start to test endpoints in your server, the first thing you'd do is create a collection. Press that little **+** button on the left column.

<img src="https://d2kbulfv42d43j.cloudfront.net/2022/Q4/postman-create-new-collection.png" caption="Create new collection" alt="Create new collection" position="center" />

Give it a name. I'm going to name it **Postman Premier**.

There are a lot more things that can be done with a Collection. But for now, let's not get deep into it.

Note: If you don't have an API to test, you can refer to my previous blog posts: [Building a Book Store API in Golang With Gin](/posts/2022/building-a-bookstore-api-in-golang-with-gin/) and [How to Integrate Swagger UI in Go Backend - Gin Edition](/posts/2022/how-to-integrate-swagger-ui-in-go-backend-gin-edition/) where I show how you can develop your simple CRUD server in Go. It's worth a look.

## Working with Requests

I am going to test my gingo server, which is a CRUD server I have developed before. I already have linked them above.

### Creating a GET Request to get introduced to UI

I have already run my gingo server and I am going to make a GET request at `http://localhost:8090/api/v1/books`.

Creating a request is straightforward in Postman. Let's start with creating a GET request.

When you expand your created collection on the left column, you'll see a link called **Create a request**. Click on that, and a tab will open in the main column.

In that window, a text will already be selected. This is the identifier of the request. I like to name my request the same as the path of the endpoint. In my case, I'm going to name it `/books`.

The next thing you do is select a **verb**. There is a dropdown just below the name of the request. This will by default be `GET`. For this particular request, we don't modify that.

Next, we'll input the address of the endpoint we need to hit. I've input `http://localhost:8090/api/v1/books`.

We don't need any other setting for now. Don't be intimidated by the UI if you don't understand it yet.

I have recorded a gif for your reference. Here it goes. 

<img src="https://d2kbulfv42d43j.cloudfront.net/2022/Q4/postman-create-a-get-request.gif" caption="Create a GET request" alt="Create a GET request" position="center" />

What we covered in this section: Creating a request, request name, request verb, and request path.

### Path Parameters

We can get all books. Let us get a specific book; by ISBN.

The quickest way to create our next request is to duplicate the previous one and modify the duplicated one.

Let us name this new request `/books/:isbn`. For the path, we're going to use `localhost:8090/api/v1/books/:isbn`. As soon as you write `:isbn` in the path input, **Params** section will be highlighted.

When you navigate to that tab, you'd see `isbn` is already added as KEY in **Path Variables** section. You need to provide value. You can get ISBN from the response of the previous endpoint we tested. E.g. `9781612680194`.

When you do this much, you should see a single book in the response, unlike the previous response, which had all the books.

Below is a gif for this section.

<img src="https://d2kbulfv42d43j.cloudfront.net/2022/Q4/postman-working-with-path-params.gif" caption="Working with path params" alt="Working with path params" position="center" />

### Creating a POST Request and working with Body and Headers

Duplicate the first endpoint we created again, but this time, change the verb to `POST`.

In the previous section **Params** section was highlighted. This time you need to highlight the **Body** section.

When you highlight **Body**, you'll see a group of radio buttons. Click on the one labeled with **raw**. A dropdown will appear at the right with the text **Text**. Click on the dropdown and select **JSON**.

When you select JSON from the dropdown, a new header is added to the request. You can see the header when you highlight the **Headers** tab. In this tab, you can see many other headers already added by Postman.

When the header is set, use the following body to make a POST request:

```json
{
    "isbn": "9780137081073",
    "title": "The Clean Coder",
    "author": "Robert C. Martin"
}
```

Here is a gif of me doing the same thing.

<img src="https://d2kbulfv42d43j.cloudfront.net/2022/Q4/postman-working-with-body-and-header.gif" caption="Working with body and header" alt="Working with body and header" position="center" />

For those who don't know. Headers are not limited to POST requests. It might be required for a GET endpoint to have an auth token in its header.

Making requests for other verbs such as DELETE and PUT is no different. I left it over for you to try with those.

## Working with variables

### Using Collection variables

We have different variable scopes available when working with Postman:

Global > Collection > Environment > Local

They all have their use case:

- **Global** - Global variables are global to all the collections you have in Postman. This should be mostly avoided.
- **Collection** - This one is my favorite. You can have collection-level variables for say credentials, baseurl, etc.
- **Environment** - If you are testing a collection with multiple data sets or conditions. Environment variables come to use.
- **Local** - Local variables are local to request and will override all other scopes variables. 

I'll demonstrate **Collection** variables, but all behave the same way and have similar UI.

Click on the Postman Premier collection and you'll see 4 tabs. _Authorization_, _Pre-request Script_, _Tests_ and _Variables_. Click on the variables.

Collection Variables use case: We are doing a lot of repetitions in each of the requests. We are inputting the base URL of the server each time. If we had to somehow modify the port address, we would have to modify it for all.

Let us change that to use a variable. If we ever need to change the value of the baseurl, we'll only be changing that in a single place.

When you see the variables tab, you'll see a table with 3 columns. Namely VARIABLE, INITIAL VALUE, and CURRENT VALUE. Set VARIABLE = `baseUrl`, INITIAL VALUE = `http://localhost:8090/api/v1`, CURRENT VALUE = `http://localhost:8090/api/v1`. INITIAL_VALUE and CURRENT_VALUE are the same here, but CURRENT_VALUE can be programmatically changed during request-response life cycle.

<img src="https://d2kbulfv42d43j.cloudfront.net/2022/Q4/postman-using-collection-variables.gif" caption="Working with collection variables" alt="Working with collection variables" position="center" />

Now change all the occurrences of `http://localhost:8090/api/v1` in the collection's URL section to `{{baseUrl}}`. This will be a manual process, but this is worth it.

### Saving response data in variables

Why would you want to save response data in a variable?

That is a good question to ask. One such use case is user login. When you log in to a service, you'd get some kind of token with a certain validity time. That token is needed to make further requests. We can add a header using **Pre-request script** using the variable we save.

Our gingo server does not have a user authentication module right now. Let us try saving `isbn` from a GET request.

This may sound a little bit misleading, but anything you want to do after a request goes inside the **Tests** tab. This also includes setting a variable for a session.

Go to the **Tests** section of `/books/:isbn` and add this javascript code:

```javascript
const body = pm.response.json()
pm.collectionVariables.set("isbn", body.isbn);
```

The code is straightforward. We are storing the JSON response in a const called `body`. Then we access the collection variable using `pm.collectionVariables`. We then set the variable name `isbn` with the value of `body.isbn`.

Here is me doing the same thing.

<img src="https://d2kbulfv42d43j.cloudfront.net/2022/Q4/postman-saving-response-data-in-variables.gif" caption="Saving response data in variables" alt="Saving response data in variables" position="center" />

Similar to collection variables, we can set any scope of variable we discussed above.

## Conclusion

In this post, we saw some basic use cases of Postman. In upcoming posts, we'll see more advanced use cases. Until then, subscribe and stay updated.