Using Postman: Your Visual API Testing Toolkit

While cURL is powerful, sometimes you need a visual interface to test APIs. That is where Postman comes in. Postman is the most popular API testing tool in the world, used by over 30 million developers. It lets you build, test, document, and share API requests — all through a user-friendly graphical interface.

In this module, we will walk through Postman step by step, from installation to advanced features like collections and variables.

Learn Postman API testing tutorial at Postman

---

1. What Is Postman?

Postman is a desktop application (and web app) designed specifically for working with APIs. Think of it as a visual version of cURL with many extra features.

Why Use Postman?

Feature	cURL	Postman
Visual interface	No	Yes
Save and organize requests	Manual (scripts)	Built-in collections
View formatted JSON	Requires jq	Automatic
Environment variables	Manual	Built-in
Test automation	Scripting required	Built-in test runner
Share with team	Copy/paste commands	Export/import collections
Request history	None	Full history
Authentication helpers	Manual headers	GUI configuration

When to Use Postman vs cURL

Scenario	Best Tool
Quick one-off test	cURL
Exploring a new API	Postman
Automated scripts/CI	cURL
Documenting API requests	Postman
Sharing API tests with a team	Postman
Debugging complex requests	Postman

graph LR
    A[API Testing] --> B{Quick test?}
    B -->|Yes| C[cURL]
    B -->|No| D{Need to save?}
    D -->|Yes| E[Postman]
    D -->|No| F{In a script?}
    F -->|Yes| C
    F -->|No| E

    style A fill:#4f46e5,color:#fff
    style C fill:#0891b2,color:#fff
    style E fill:#059669,color:#fff

---

2. Installing Postman

Step 1: Download Postman

Visit postman.com/downloads and download Postman for your operating system:

• macOS: Download the .dmg file and drag to Applications
• Windows: Download the .exe installer and run it
• Linux: Download the .tar.gz or use snap: snap install postman

Step 2: Create a Free Account

When you first open Postman, you will be asked to create an account. You can:

• Sign up with email
• Sign in with Google
• Skip sign-in (limited features)

A free account is recommended because it allows you to save your work and sync across devices.

Step 3: Explore the Interface

When Postman opens, you will see several key areas:

graph TD
    A[Postman Interface] --> B[Sidebar - Collections and History]
    A --> C[Request Builder - Main Area]
    A --> D[Response Viewer - Bottom Panel]

    C --> C1[Method Dropdown - GET, POST, etc.]
    C --> C2[URL Bar - Enter API endpoint]
    C --> C3[Tabs - Params, Auth, Headers, Body]
    C --> C4[Send Button]

    D --> D1[Response Body - JSON result]
    D --> D2[Status Code - 200, 404, etc.]
    D --> D3[Response Time - milliseconds]
    D --> D4[Response Headers]

    style A fill:#4f46e5,color:#fff
    style C fill:#0891b2,color:#fff
    style D fill:#059669,color:#fff

---

3. Making Your First GET Request

Let us make a GET request to fetch a post from JSONPlaceholder.

Step-by-Step

1. Open Postman and click the + button to create a new request tab.

2. Select Method: The dropdown on the left should say GET (this is the default).

3. Enter URL: In the URL bar, type:

   https://jsonplaceholder.typicode.com/posts/1
   

4. Click Send: Press the blue Send button.

5. View Response: In the bottom panel, you will see:

   • Status: 200 OK (green badge)
   • Time: Response time in milliseconds
   • Size: Response size in bytes
   • Body: The JSON response, automatically formatted:

{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body": "quia et suscipit\nsuscipit recusandae consequuntur..."
}

That is it! You just made your first API call in Postman.

Try These GET Requests

Practice with these endpoints:

URL	What It Returns
https://jsonplaceholder.typicode.com/posts	All 100 posts
https://jsonplaceholder.typicode.com/users	All 10 users
https://jsonplaceholder.typicode.com/users/1	User with ID 1
https://jsonplaceholder.typicode.com/posts/1/comments	Comments on post 1
https://jsonplaceholder.typicode.com/todos	All todos

---

4. Sending a POST Request

Now let us create a new resource by sending a POST request.

Step-by-Step

1. Create new tab: Click the + button.

2. Change Method: Click the dropdown and select POST.

3. Enter URL:

   https://jsonplaceholder.typicode.com/posts
   

4. Set Headers: Click the Headers tab and add:

   • Key: Content-Type
   • Value: application/json

   (Postman often adds this automatically when you set the body, but it is good practice to verify.)

5. Set Body: Click the Body tab, then:

   • Select raw
   • From the dropdown on the right, select JSON
   • Enter this JSON:

{
  "title": "My First Postman Post",
  "body": "This was created using Postman!",
  "userId": 1
}

6. Click Send

7. View Response: You should see:

   • Status: 201 Created
   • Body:

{
  "title": "My First Postman Post",
  "body": "This was created using Postman!",
  "userId": 1,
  "id": 101
}

The server created the resource and assigned it id: 101.

---

5. PUT and PATCH Requests

PUT Request (Full Update)

1. Method: PUT
2. URL: https://jsonplaceholder.typicode.com/posts/1
3. Body (raw JSON):

{
  "id": 1,
  "title": "Completely Updated Title",
  "body": "This entire post has been replaced via PUT.",
  "userId": 1
}

4. Send → You should get 200 OK with the updated data.

PATCH Request (Partial Update)

1. Method: PATCH
2. URL: https://jsonplaceholder.typicode.com/posts/1
3. Body (raw JSON):

{
  "title": "Only the Title Changed"
}

4. Send → You should get 200 OK. Notice only the title changed; the body and userId remain the same.

---

6. DELETE Request

1. Method: DELETE
2. URL: https://jsonplaceholder.typicode.com/posts/1
3. No body needed
4. Send → You should get 200 OK with an empty object {}.

---

7. Understanding the Response Panel

Postman's response panel has several important tabs:

Body Tab

Shows the response data. You can view it in several formats:

View	Purpose
Pretty	Formatted, color-coded JSON (default)
Raw	Unformatted response text
Preview	HTML preview (for web pages)

Headers Tab

Shows all response headers from the server:

Content-Type: application/json; charset=utf-8
Cache-Control: max-age=43200
X-Powered-By: Express

Test Results Tab

Shows results from any test scripts you have written (we will cover this later).

Response Metadata

At the top of the response panel, you will see:

• Status: 200 OK or 404 Not Found, etc.
• Time: How long the request took (e.g., 234 ms)
• Size: Response size (e.g., 292 B)

---

8. Working with Query Parameters

Instead of typing query parameters directly in the URL, Postman lets you add them visually.

Step-by-Step

1. Enter base URL: https://jsonplaceholder.typicode.com/posts

2. Click Params tab (next to the URL bar)

3. Add parameters:

Key	Value
userId	1

4. Postman automatically updates the URL to:

   https://jsonplaceholder.typicode.com/posts?userId=1
   

5. Send → You will get only posts by user 1.

Adding Multiple Parameters

Add more rows in the Params tab:

Key	Value
userId	1
_limit	5

URL becomes: https://jsonplaceholder.typicode.com/posts?userId=1&_limit=5

You can toggle parameters on and off by unchecking the checkbox next to each one.

---

9. Working with Headers

Viewing Default Headers

Click the Headers tab. Postman automatically sends some headers:

• User-Agent: PostmanRuntime/...
• Accept: */*
• Accept-Encoding: gzip, deflate, br

Adding Custom Headers

Click Headers and add your own:

Key	Value
Content-Type	application/json
Accept	application/json
X-Custom-Header	my-value

You can toggle headers on and off without deleting them.

---

10. Authentication in Postman

Postman has a dedicated Authorization tab that simplifies authentication.

Using the Authorization Tab

1. Click the Authorization tab in your request.

2. Select the Type from the dropdown:

Type	Use Case
No Auth	Public APIs
API Key	APIs using key-value authentication
Bearer Token	APIs using JWT tokens
Basic Auth	Username/password authentication
OAuth 2.0	Apps requiring OAuth flow

Bearer Token Example

1. Select Bearer Token from the Type dropdown.
2. Paste your token in the Token field.
3. Postman automatically adds the Authorization: Bearer YOUR_TOKEN header.

API Key Example

1. Select API Key from the Type dropdown.
2. Enter the key name (e.g., X-API-Key or api_key).
3. Enter the key value.
4. Choose whether to send it in the Header or Query Params.

---

11. Organizing Requests with Collections

Collections are Postman's way of organizing related requests into folders.

Creating a Collection

1. Click Collections in the left sidebar.
2. Click the + button to create a new collection.
3. Name it: REST API Course - JSONPlaceholder.

Adding Requests to a Collection

1. Make a request (e.g., GET /posts/1).
2. Click Save (or Ctrl/Cmd + S).
3. Give it a name: Get Single Post.
4. Select your collection.
5. Click Save.

Organizing with Folders

Inside a collection, create folders for each HTTP method:

graph TD
    A["REST API Course Collection"] --> B["GET Requests"]
    A --> C["POST Requests"]
    A --> D["PUT/PATCH Requests"]
    A --> E["DELETE Requests"]

    B --> B1["Get All Posts"]
    B --> B2["Get Single Post"]
    B --> B3["Get User Posts"]
    B --> B4["Get Post Comments"]

    C --> C1["Create New Post"]
    C --> C2["Create New User"]

    D --> D1["Update Post - PUT"]
    D --> D2["Patch Post Title"]

    E --> E1["Delete Post"]

    style A fill:#4f46e5,color:#fff
    style B fill:#0891b2,color:#fff
    style C fill:#059669,color:#fff
    style D fill:#d97706,color:#fff
    style E fill:#dc2626,color:#fff

---

12. Using Variables

Variables let you reuse values across requests. Instead of typing the base URL every time, store it as a variable.

Creating Collection Variables

1. Click on your collection name.
2. Go to the Variables tab.
3. Add a variable:

Variable	Initial Value	Current Value
baseUrl	https://jsonplaceholder.typicode.com	https://jsonplaceholder.typicode.com

Using Variables in Requests

Replace the hardcoded URL with the variable using double curly braces:

GET {{baseUrl}}/posts/1
POST {{baseUrl}}/posts
PUT {{baseUrl}}/posts/1
DELETE {{baseUrl}}/posts/1

Now if the API URL changes, you only update it in one place.

Environment Variables

Environments let you switch between different configurations:

Development Environment:

Variable	Value
baseUrl	http://localhost:3000/api
apiKey	dev-key-12345

Production Environment:

Variable	Value
baseUrl	https://api.myapp.com
apiKey	prod-key-67890

Switch environments from the dropdown in the top-right corner of Postman. All your requests automatically use the correct URLs and keys.

---

13. Postman Console

The Postman Console is like cURL's -v flag — it shows the raw HTTP conversation.

Opening the Console

Click View → Show Postman Console (or press Ctrl/Cmd + Alt + C).

The console shows:

• The complete request (method, URL, headers, body)
• The complete response (status, headers, body)
• Timing information
• Any errors

This is invaluable for debugging when a request does not work as expected.

---

14. Exporting and Sharing

Export a Collection

1. Right-click your collection.
2. Select Export.
3. Choose format (v2.1 recommended).
4. Save the JSON file.

You can share this file with teammates, include it in Git repositories, or import it on another machine.

Import a Collection

1. Click Import in the top toolbar.
2. Drag and drop a .json collection file.
3. Your requests are now available.

Generate Code from Postman

One of Postman's best features: it can convert any request into code in dozens of languages.

1. Click the Code button (to the right of the Send button, shown as </> icon).
2. Select your language: cURL, Python, JavaScript, Java, Go, etc.
3. Copy the generated code.

For example, a POST request becomes:

cURL:

curl --location 'https://jsonplaceholder.typicode.com/posts' \
--header 'Content-Type: application/json' \
--data '{
    "title": "Postman Post",
    "body": "Generated code!",
    "userId": 1
}'

Python (requests):

import requests
import json

url = "https://jsonplaceholder.typicode.com/posts"
payload = json.dumps({
    "title": "Postman Post",
    "body": "Generated code!",
    "userId": 1
})
headers = {
    'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, data=payload)
print(response.json())

---

15. Postman vs cURL: Quick Reference

Here is how the same operations look in both tools:

GET Request

cURL:

curl https://jsonplaceholder.typicode.com/posts/1

Postman: Method: GET, URL: https://jsonplaceholder.typicode.com/posts/1, Click Send.

POST Request

cURL:

curl -X POST https://jsonplaceholder.typicode.com/posts \
  -H "Content-Type: application/json" \
  -d '{"title": "Test", "body": "Content", "userId": 1}'

Postman: Method: POST, URL: https://jsonplaceholder.typicode.com/posts, Body tab: raw JSON, Click Send.

Authenticated Request

cURL:

curl -H "Authorization: Bearer token123" https://api.example.com/data

Postman: Authorization tab: Bearer Token, paste token123, Click Send.

---

Summary and Key Takeaways

1. Postman is the industry-standard visual API testing tool.
2. Use it for exploring, documenting, and organizing API requests.
3. The interface has three main areas: sidebar (collections), builder (request), and viewer (response).
4. Collections organize requests into logical groups with folders.
5. Variables eliminate hardcoded values and enable environment switching.
6. Code generation converts Postman requests into any programming language.
7. The Postman Console shows raw HTTP details for debugging.
8. Use Postman for exploration; use cURL for automation and scripting.

---

Lesson Review Quiz

---

Practice Exercise

1. Install Postman if you have not already.

2. Create a collection called "REST API Course".

3. Add these requests to the collection:

   • GET all posts
   • GET a single post (ID 1)
   • POST a new post
   • PUT update post 1
   • PATCH update post 1 title
   • DELETE post 1

4. Create a variable called baseUrl with value https://jsonplaceholder.typicode.com and update all your requests to use it.

5. Use the code generator to convert your POST request into cURL and Python code.

6. Export your collection as a JSON file.

In the next module, we will dive deeper into status codes, query parameters, path parameters, and authentication.