Jul 12, 2016

Working with the Postman REST Client

Recently at one of my clients, I found myself looking for a different setup for building and managing REST calls to various APIs I was working with. There are a multitude of services out there that seek to help with this problem, and while sifting through them I found one that has exceeded my expectations: Postman.

Available as a Chrome extension, as well as a Mac application, Postman is a robust, multi-featured application that helps you build, test, and share REST API calls easily. It’ very easy to use despite its depth of features, and I find myself discovering new ways to use it very often. I wanted to create this blog post as a quick Postman primer, to showcase some of its shining features.

Postman Basics

The basic interface of Postman is probably similar to ones you’ve seen before:

PostmanScreen

Here at our basic request screen we can select our request type, set our headers, fill our the request body, and do all the other basics that we’re familiar with. Postman offers us a number of options for how we choose to enter in this information, but it also allows us to generate code snippets for multiple different languages that would also make this call:

PostmanCodeGeneration

This way I can easily take one request and put it in whatever code I am working with!

In addition to exporting a single request that way, I can also label and save my requests to collections that I can share with anyone who uses Postman. These collections are convenient ways to organize, share, and even test all my requests. (More on that later in the post!)

For example, while I was developing an API with a coworker, there were many times when we needed to access several REST calls that the other had been working on. Rather than having to check the docs and manually build the correct request, he was able to generate a link for his request collection that I was able to import into Postman. Within seconds I had access to all his API calls without having to manually enter them in.

This was also invaluable when working with our QA team. Once we were done building our endpoints and turned the work over to QA, we were able to share our API calls with them so they could get a good look at how the APIs were supposed to function and what the calls looked like. In addition, if they ran into any issues while testing, they could easily send us the request they were using so we could recreate the exact call ourselves. It saved us a lot of headaches when debugging issues in the long run.

To share an API call all you have to do is select the “…” menu on a collection and select “Share”. This will display the following popup:

PostmanShareCode

Postman gives us the option to share a direct link or even generate some code for embedding a button/link to the collection in a website!

Postman Variables

One pain point for me when doing API development was working with multiple different environments. Each environment has its own auth token, its own url, and maybe its own headers. It was tedious to make the same request to multiple environments, because I’d have to be switch data all the time. However, Postman makes this easy with its use of Global Variables and Environment Variables.

For instance, let’s look at this example where I am attempting to retrieve a post object from an endpoint while passing an Authorization header:

Local Request:

PostmanLocalCall

QA Request:

PostmanQARequest

I’ve got two requests to the same endpoint that are in different environments. Instead of manually creating these requests, I can create environment “profiles” in which I set up some key/value pairs of data like this:

PostmanEnvironment

By making one for each environment I can insert the values as variables in the format {{key}} anywhere in the request:

PostmanVariables

Now all I have to do to target a different environment is select one of my profiles from a drop down. This makes it fast and easy to make a call to multiple environments and has saved me a lot of time when debugging issues between environments. In addition, Postman has Global Variables which we can use the same way, but are available in all environments.

On a small related note, Postman also has a handful of “Dynamic Variables” which you can use. Putting “{{$guid}}” will generate a guid where you put it in the request. “{{$timestamp}}” will put in the current timestamp, and “{{$randomInt}}” will generate an integer between 0 to 1000. I’ve found these to be useful time savers when developing spinning up requests.

Testing

One of the areas that really shines in Postman is the built in testing capabilities that it offers.  Each request that you write has an area where you can access the request/response data and use them to write tests for your requests like so:

Here we can see that the request/response data are given to us by Postman and can easily be parsed out to use in tests. In addition, Postman gives us access to data like the response code, easily accessible through the “responseCode” object we are given. It also offers a ‘postman’ object which has a number of utility methods on it. In the example above we use it to grab the Content-Type header from the response.

Everything written in this area is in JavaScript, so it’s easy to jump right in and start writing. Tests should be written in the following format:

“tests” is an object that Postman uses to keep track of the tests it needs to execute. The string key you pass in is the description that will be displayed whenever the tests are run. Finally, the code on the right side should evaluate to a boolean. As long as you adhere to that format, you’re free to write as simple or complex tests as you like.

Any tests you write on a request will be executed every you fire it off, but you can also use collections to run several tests at once. Postman has a Test Runner utility that can help us put out tests through their paces.

Test Runner

This is the test runner utility screen:

PostmanTestRunner

Here we can access our collections of requests to set up a test run, as well as access old test runs to compare results. After selecting a collection, we can set our environment, select a number of iterations, and specify a delay between each request (optional). With all that done we’re off to the races, and we get a great view of the test results, the status code, and the time for each test run.

PostmanTestResults

However, to fully test most APIs we might want to send several different requests with different sets of data to the endpoints. Writing a request and tests for each different permutation of data could get tiresome and tedious, even if we have a cool test runner to run them all when we’re done. Thankfully, Postman has us covered in this regard as well!

On the test runner screen we are given the option to choose a data file. This data file can be either a CSV or a JSON file, but will allow us to set up data in bulk to be run through the test runner. For example:

username firstName lastName age
luke.skywalker Luke Skywalker 19
han.solo Han Solo 29

When using a CSV file, the first row of the file needs to contain the variable name each column. Beyond that, we can enter in as many permutations of the data as we want. With that done, we have a file that we can use but we still have a little work to do on the Postman side. In our requests that we are using this data for, we need to set up the variables to be used. Following the syntax of the environment variables, we can set up the requests to use the data from the file:

With our data ready, and our requests properly set up we can return to the test runner screen. Now when we create our test run, we can upload our CSV as part of the run and Postman will run a request for every single row in the table. Just like that, we’ve written one request and run it for countless different combinations of data!

Conclusion

Having used it for a few months now, I feel I’ve only scratched the surface of what Postman has to offer. There are numerous other features including a built in proxy, team sharing, and even a fully featured CLI called Newman! I would highly recommend giving Postman a look to see if it could help you too.

About the Author

Object Partners profile.

One thought on “Working with the Postman REST Client

  1. Samseen says:

    Great Article mate!

  2. Isma says:

    Hello Nathan, I am hoping you can give me an idea regarding this project I am trying to accomplish. I am trying without luck to see if I can configure Postman to link/connect to work with gravity forms via API call. instead of creating forms manually by login to word press website and start working with gravity forms, I would like to see if i could streamline some of it through API that would be awesome. Thank you

  3. srini says:

    Hi Could you please let me know how to get past or future timestamp? per1 hour or 2 hour prior to the sys date?
    my request is like below

    url?starttime=2017-10-25T12:00&endtime=2017-10-25T13:00 also i need end date equal to sys date and time in UTC format, rite now i am doing manually every morning or evening to check my APIs are getting the data, I want to do it dynamically, no need to go every day and do hard coding.

    http://host.php?timestamp=2017-10-24T13:00&endTimestamp={{timestampUtcIso8601}}

  4. Tehseen says:

    Can we schedule REST api calls using POSTMAN?

Leave a Reply to srini Cancel reply

Your email address will not be published.

Related Blog Posts
Natively Compiled Java on Google App Engine
Google App Engine is a platform-as-a-service product that is marketed as a way to get your applications into the cloud without necessarily knowing all of the infrastructure bits and pieces to do so. Google App […]
Building Better Data Visualization Experiences: Part 2 of 2
If you don't have a Ph.D. in data science, the raw data might be difficult to comprehend. This is where data visualization comes in.
Unleashing Feature Flags onto Kafka Consumers
Feature flags are a tool to strategically enable or disable functionality at runtime. They are often used to drive different user experiences but can also be useful in real-time data systems. In this post, we’ll […]
A security model for developers
Software security is more important than ever, but developing secure applications is more confusing than ever. TLS, mTLS, RBAC, SAML, OAUTH, OWASP, GDPR, SASL, RSA, JWT, cookie, attack vector, DDoS, firewall, VPN, security groups, exploit, […]