Postman Tutorial

Introduction to Postman

The following is a common scenario, there is a new requirement in your application (or data pipeline, website, report, etc.) and you realize that you can save hundreds of hours in development if you leverage and existing service that makes available the logic/data/service via an existing API’s for anyone to consume.  Now you have to integrate this API into your development environment and get the results you are looking for, but you have yet to understand how the API works. Yes, you’ve seen the API documentation, you know how to call API’s in your development language of choice, but you are looking to quickly see the API in action, make sure the service is accessible, run an API request, see the data, you get the idea.  You want to quickly test the API without having to write code in you application and make sure everything works as expected. One way to do this is to leverage Postman.

Postman describes itself as a platform to build and use API’s, and we’ll use it today to quickly test an API.

We’ll use this sample use case as an example: Our application order page needs to check that the zip code provided by the customer is a valid US and not a PO Box because you can’t deliver your product to PO Boxes. You find Metadapi’s Zip Code API with all of the US zip codes and realize that you can get this requirement done very quickly by leveraging the data provided by this API.  

Let's get started !

Installing Postman

The first thing you need to do is download Postman (https://www.postman.com/downloads/) . You also have the option to use the browser version of Postman (if you don’t want to download any software).  All your data can synch between your local installation and the Postman service so it makes portability really easy. 

Navigating the Interface

When you open Postman the first thing you want to do to get running quickly is to select the Workspaces tab

Workspaces are a way to organize your work, the work of teams the organization’s work within Postman. If you are working in a team, and several people need access to API requests, then a team workspace is needed so you can share the work with other members of your group.

To get started we'll be using a personal workspace. We we need to create a Collection. A collection is a way to save different API requests. Collections can be organized in many different ways, by project, by API, by department, etc. For our use case we’ll create a Collection called “Zip Code API”.

Click the plus sign in the collections tab.

The new collection details appear:

Type the name of the collection as Zip Code API.

We are going to put all the different API requests to the Zip Code API in this collection. Since we are only using API’s from Metadapi in this example, to save time we’ll add the API Key to the collection so that every request we put on this collection automatically adds the API key.  All your Metadapi API keys are located in the My API’s page in your account. We get the value of the API key here to add it to the postman authorization. 

In the Zip Code collection click the authorization tab and select API Key

The following information is needed to setup the API Key:

1. The name of the key: Ocp-Apim-Subscription-Key
2. The value of the key:
3. The location of the key: Header.

Click the “Save” button.

Any API we place in this collection will include this heading.

Next, we’ll add a request to the collection.

This will open the add request window.

We’ll add the following information:

1. We’ll name the request: Get Valid Zip Code Not a PO Box
2. We select a GET operation.
3. We’ll use the Zip Code Details endpoint like this:

https://global.metadapi.com/zipc/v1/zipcodes/90210

Click the send button to execute !

We have executed our first API in Postman !

We can now explore the data returned by the API to get a better understanding of the code we need to write. 

The endpoint documentation shows us that the element zipClassificationCode has a specific value when a zip code is a PO Box (Value of P)

When exploring the result we see in the payload the code that is available on this specific zip code.

Our testing team let’s us know that zip code 90009 in California is a PO Box. We have 2 choices now with Postman:

1. We just replace the zip code on the existing call or
2. We create a new GET request on the folder and give it a different name.

Both options are valid, after all we are trying to test the data, our preference is to always save different calls (even if they use the same end point) on different requests because then we can easily view and replicate different test cases as they come along. (those tests can also be automated). 

So we now create a new GET request called Get Valid Zip Code PO Box

And we see the PO Box classification code in the results.

We do the same process to create 2 more scenarios, a valid syntax but invalid zip code (i.e. 11111) and invalid syntax zip code (i.e. house).

After exploring the result of the valid syntax but invalid zip code we see there is no data object and the count on the meta object is set to 0.

Next we create a new request called Invalid syntax, and instead of using a zip code value, we pass a random word. In this example the word "house". 

The invalid syntax returns something completely different:

This time the API fails with a 400 Bad Request and the error message specifies that the syntax is incorrect. So now we have created 4 different types of calls, we understand how the data is return and what’s happens on each different case when dealing with the Zip Code API. We can now take this information and create the necessary code (you can use any programming language to call this API).

Our Postman Collection should look like this:

As you can see, using Postman as a client tool to run API calls is really easy. But the tool itself has a lot of functionality that is not covered in this tutorial, we just scratched the surface when it comes to postman. 

Next Steps

1. Check the Postman Getting started guide. This is an excellent easy to read tutorial on all things Postman. 
2. If you like video tutorials, the course "Postman Beginner's Course - API Testing" is a very complete tutorial on how to use postman. It's 2 hours long but it's easy to follow along.