How to make a request using Postman

As technical writers, we should be able to test the endpoint we are documenting. To do so, we need to use GUI clients like Postman.

Postman is a popular Graphical User Interface (GUI) client used to make and save requests and perform other API-related tasks. Postman can also show the response to these requests in prettified JavaScript Object Notation (JSON) or raw format. Most people prefer Postman because it is easy to configure, allows us to easily see the request and response headers, and works efficiently on both Mac and PC.

There is a web and app version of Postman, but we'll use the web version for this task. The app version is available for download here.

The task we are about to perform was one of the activities in Tom Johnson’s API documentation course; hence, we will obtain our endpoint and key-value pairs from there.

To get started, we need API keys to authenticate our request. Requests need authorization because it allows the API providers to permit access to the API, impose restrictions on some features within the API, and rate limit the number of requests that can be made.

Let’s get API keys for the OpenWeatherMap API.

1. Visit https://openweathermap.org/.

2. Click on "Sign in" at the top left corner of the dashboard (Figure 1). The "Sign In To Your Account" page will appear.

3. Click the "Create an account” (Figure 2) option.

4. Input your details and press the “Create New Account” button (Figure 3).

5. Click on “API keys.”A new page will appear with your authentication key on it. Copy the key to a place where it is easily accessible when needed (Figure 4).

Now that you have gotten your API key, let’s focus on our main aim, to make a request using Postman.

We'll use the following OpenWeatherMap API endpoint to make a request using postman:

GET https://api.openweathermap.org/data/2.5/weather

Also, we will be using the following key-values pairs as our parameters:

• Key: zip / value: 95050

• Key: units / value: imperial

• Key: appid / value: (your API key)

We'll include the API key as the value for our appid.

Making requests using Postman

1. Press this link and click "Sign Up for Free" in the top right corner of your screen (Figure 6).

2. Input the details and click "create free account" (Figure 7).

3. Skip the welcome messages until the "My workspace" page appears (Figure 8). Click the "Send your first API request" at the left section of the "My Workspace" page (Figure 8). A request page will appear (Figure 8).

4. Input the endpoint below in the box next to GET (Figure 9).

https://api.openweathermap.org/data/2.5/weather

The page should look like this:

5. Input the key-value pairs below in the rows underneath the "Query Params" tab (Figure 10).

• Key: zip / value: 95050

• Key: units/value: imperial

• Key: appid / value: (your API key)

The page should look like this:

Note: While working with some APIs, we may have to pass the API key in the header rather than as a query parameter. In such situations, click the headers tab and insert the key-value pair.

6. Press "SEND" next to the endpoint URL. The response will appear underneath the parameters (Figure 11).

7. To save your request, click the "Save" tab just above the "SEND" button. A "SAVE REQUEST" page will appear (Figure 12).

8. Input any name of choice in the Request name box. Include a name that can easily be referenced for future purposes. Optionally, include a description of the request in the add description box (Figure 13).

9. Click the "New Collection" tab at the bottom left of the page to create a collection in which you will save your request.

10. Give your collection a name, and click "Create." Select your collection and click the "Save" tab (Figure 14).

11. Last, we will be returned to the "My workspace" page. The new collection is on the left side of the page (Figure 15).