What is Postman?

Postman is a popular API client that makes it easy for developers to create, share, test and document APIs. This is done by allowing users to create and save simple and complex HTTP/s requests, as well as read their responses. The result – more efficient and less tedious work.

Postman came to life in 2012 as a Chrome extension built as a side project. Since then, a simple tool grew into a native application for Windows, Mac, and Linux along with the Newman command line utility, augmented by a SaaS cloud service dubbed Postman Pro. Postman was founded in 2014 with offices in San Francisco and Bangalore.

Getting Started

When you install and start Postman for the first time, the application will ask you to sign in. It’s free to sign up (unless you choose to sign up for Postman Pro), but it’s not strictly necessary, so you can choose to skip registration and head right for the main screen.

A window that is shown at the start of each session (unless you uncheck “Show this window on launch”) allows you to create a new instance of each of the building blocks used in Postman. Let’s have a look at those:

• A Request is a single HTTP request, such as calling an API operation.
• A Collection is a number of requests grouped together. A collection could, for example, represent a complete Web API offered by a service, with each of the requests representing one possible operation in the API. In this aspect, a Collection can be considered to be similar to an OpenAPI definition.
• An Environment is a container of configuration variables you need for your API work. For example, if you need to work on an API and test it with different API keys, you could store each of those keys in a separate environment and select the one you need. For this introduction post, we won’t use them, though.

The most direct way to get started using Postman is to forego setting up these blocks, close the window and just start making HTTP requests straight away. Many developers debug API calls in the browser or use a command line utility such as curl, and you can similarly use Postman: choose a method, enter your URL, add headers or body parameters and hit Send. As an example, you could test with the JSON Placeholder API, an API that returns dummy data for the sole purpose of testing API requests.

Postman makes the HTTP request on your behalf and then displays the response below. You’ll see relevant information for debugging, such as how long the request took and which headers were returned.

You can continue using Postman in this way and make all your requests manually, leveraging multiple tabs if you need to work on various requests at the same time. Every request is recorded in a history, so you can always go back and repeat your API calls. The history is shown on the left side of the screen, where you can toggle between History and Collections tabs.

Even if you only use Postman like this, you’re already one giant step ahead of just using curl concerning user-friendliness. However, you’ve barely scratched the surface of what Postman is capable of.

Working with Requests and Collections

You can merely make requests and recall them from History, but grouping them into collections makes them more easily accessible. You can store requests as quickly as you can send them; in fact, the Savebutton is right next to Send. When storing requests you can give them a name and description and assign them to an existing collection, or create a new one.

Hold on for a moment, though. As you can see in the screenshot, I’ve requested https://jsonplaceholder.typicode.com/posts/1, which means I’m retrieving a post with the ID 1. For collections it makes a lot of sense not to include this ID, so we can use the stored request as a generic template to fetch any post. Replace 1 in the URL with :id. In Postman collections, a colon indicates a URL path parameter (unlike OpenAPI/Swagger, which uses curly braces for this purpose). If you click on the Params button you’ll see that there’s a key called id and you can provide a value for it, such as 1. Now you can save your request.

You can browse your collections and recall all requests stored in them from the Collections tab on the left side of the main Postman window.

Postman Collections and OpenAPI

As I’ve already mentioned, Postman Collections have a comparable scope and capabilities as OpenAPI definitions and thus can be used for the same purposes. It is possible to convert machine-readable API definitions from one specification format to another, which also means that Postman can be used together with Swagger or other OpenAPI tools in the same API lifecycle, or you can collaborate with developers who prefer to use other tools.

When it comes to creating collections, Postman accepts a wide variety of input formats in the Importer. Not only can you import Swagger 1.2 and Swagger/OpenAPI 2.0 (no OpenAPI 3.0 yet, though) and other formats such as RAML and WADL, you can also make the importer parse curl commands, such as the examples that API providers often include in their documentation. When you click on the Import button in the main Postman window, you’ll be prompted with the option to select a file or entire folder, import from a URL or paste raw text.

Imported OpenAPI definitions will turn into new collections that immediately pop up in the Collections tab.

When it comes to exporting your work, however, Postman speaks only their own proprietary JSON collection format. This is generally not a problem, since there are third-party tools available that do the format conversion for you. The best and most common tool for this purpose is APIMatic Transformer, which is capable of converting between virtually any machine-readable API specification format on the market.

Firstly, click on the three dots next to your collection, choose Export and save your collection on your computer. Then, go to APIMatic Transformer. Using APIMatic for this purpose is free, but you have to sign up for an account. After signing in, you can upload the exported file from Postman and request conversion into any other format.

Postman in the API Lifecycle

There are different stages of the API lifecycle in which Postman can be used. Here are a few typical examples of how the application might fit into yours:

Solo developers or small teams that work on design and implementation of the API at the same time can use Postman side-by-side with their IDE to write code and send test requests. After manual API testing , requests can be packaged up into a collection. With Postman’s Collection Runner, test cases can be defined so that API requests can be repeated automatically in the future to make sure that updates to the code don’t break the interface. The Collection can also be exported into OpenAPI for testing or processing in other tools, such as BlazeMeter.

In projects in which code is written first, and testing and documentation are done later, probably by another person, this person can test the API in Postman and build a Collection of their test cases. They can then document the API manually and build upon this Collection, as described above. Alternatively, developers could generate an OpenAPI definition from their code using one of the tools which we’ve introduced in a previous post on this blog. Testers and technical writers can use Postman’s Import feature to load this OpenAPI definition and build out the description of methods and optimize the automatically generated specification.

Teams that have adopted a proper specification-first API lifecycle can do the whole API design in Postman. All requests can be designed. Postman allows giving example responses for testing and is even capable of running a Mock Server feature that allows testing the API and creating clients without the server having been implemented yet. The Collection designed by the API authors becomes the contract and developers can load it into their own Postman to find out whether the code they’re writing adheres to the specification.

References

https://www.blazemeter.com/blog/getting-started-postman