Exploring API Requests & Responses with Postman

When it comes to actually trying out REST APIs (sending requests and seeing responses), you’ve got many tools to choose from. In this post, we’ll take a look at my absolute favorite API-related tool of all-time: Postman. Learn to use the Postman API client efficiently, and you’ll wonder how you could ever live without it!

What is Postman?

Postman is an API platform for building and using APIs. Since API Newbies is all about using REST APIs, we’ll be looking at Postman from that angle. Specifically, we’ll focus on the Postman API client, which enables you to send API requests and see the responses.

Why Postman?

When you’re exploring a new API, or in the early stages of planning your API integration, you’ll often want to test (try out) various API calls. This is where Postman comes in handy — you can use it to issue API requests and examine API responses, all without writing a single line of code. You can even save API requests as you create them in the Postman API client, allowing you to return and re-run them later if necessary (for example, when troubleshooting an issue with your API integration).

Getting started with Postman

Get started with Postman by completing the following four steps.

Step 1: Create a Postman account

Before you can start using the Postman API client, you’ll first need to create a Postman account. It’s free to create an account, and having an account will allow you to save your API requests in the Postman API client as you go.

Step 2: Download Postman

After you’ve created a Postman account, download and install the Postman app on your machine. Although the web version of Postman (which doesn’t require an install) provides much the same functionality as the Postman app, the Postman app provides a more full-featured experience. For that reason, I recommend using the Postman app over the web version of Postman, provided that you’re able to install software on your machine.

Step 3: Open and sign-in to Postman

After you’ve installed the Postman app on your machine, open it and sign-in using the account credentials you specified earlier.

Step 4: Create your first Request in Postman

After you’ve signed in to the Postman app, try it out by following the instructions in the Sending your first request section of the Postman docs. The following screenshot shows the results in Postman: the top portion shows the request (GET postman-echo.com/get) and the bottom portion shows the response (body) in JSON format.

Postman workspaces, collections, variables, & requests

Now that we’ve installed the Postman app, let’s review the main components that are most relevant to using APIs. The following diagram shows the relationship between these main components in the Postman app.

Let’s talk through this structure, from the bottom – up.

• You’ll use Postman to create, save, and submit the various API Requests that you want to test / try out. To learn more about Requests in Postman, see the Building requests section of the Postman docs.

• Collections provide a way for you to organize your Requests. For example, let’s say you’re working with the Smartsheet API and the DocuSign API. While nothing prevents you from comingling API Requests for both products within a single collection, it may be more efficient (cleaner) to save your DocuSign API requests to one collection and your Smartsheet API requests to another collection. Within a collection, you may choose to further organize your requests into Folders. For more information about managing collections, see the Grouping requests in collections section of the Postman docs.

• Workspaces provide a way for you to organize your Collections and also collaborate with others. The first time you login to the Postman app, you’ll see that a workspace named My Workspace is automatically created for you. This is a good place to create your new Collections when you’re first getting started with Postman, although as time goes on, you may want to add another level of organization/separation by creating additional workspace(s). For more information, see the Creating a workspace section of the Postman docs.

• Variables enable you to store and reuse values in Postman. For example, let’s say an API you’re working with requires that you pass the API token in the header of each API request. Defining a Variable to contain the token value and then specifying that variable in the header of each request means that if the token value ever changes, you’d only need to update it in one place (i.e., in the variable you’ve defined) and not in each and every request. Variables are commonly defined at the Collection level or at the Workspace level (via Environments). For more information, see the Using variables section of the Postman docs.

The following screenshot shows the Postman app UI, where:

• My Test Workspace is a workspace that contains 2 collections: Cat Facts and DocuSign Signature REST API
• The Cat Facts collection contains just a single request.
• The DocuSign Signature REST API collection is a fork (copy) of the public collection (published by DocuSign) that contains numerous folders, each one containing numerous requests.

Collaborating in Postman

Oftentimes you’ll be using Postman to independently test (try out) various API requests that you configure from scratch. However, there may be times when you want to collaborate with others on your team, so you can all be working from the same set of requests in Postman, rather than everyone configuring things on their own. Fortunately, Postman has some great collaboration features. And even better, Postman allows teams of up to three users to collaborate at no cost (at the time of this writing — June 5, 2022). For details about collaboration in Postman, see the Working with your team section of the Postman docs.

Using public workspaces & collections

No matter which API you’re using, do yourself a favor before you start configuring requests from scratch in Postman: check to see if there’s a public Workspace or Collection of API requests that you can fork (create a copy of) into your own Postman account. For example, let’s say I’m using the DocuSign API and want to test out some API requests. I can use the Search text box at the top of the Postman app to search the Public API Network for DocuSign. Doing so shows that there’s a DocuSign Public Workspace as well as several separate collections within that workspace (one for each DocuSign API). Awesome! Now instead of configuring all of my DocuSign API requests from scratch in Postman, I can save a ton of time by simply forking the DocuSign API collections I’ll be using (along with the workspace Environment that I can use to set values for variables that the API requests require).

So there you have it…

…a brief look at Postman — a must-have tool in your arsenal when you’re working with APIs. Although this post has barely scratched the surface of Postman capabilities, hopefully it piques your interest! I highly encourage you to head on over to the Postman docs to learn more about it.

Next up, we’ll take a look at cURL, a command-line tool for issuing API requests. But first — a quick knowledge check: