Postman, Explained — The Complete Setup & Usage Guide for API Testing

Postman, Explained — The Complete Setup & Usage Guide for API Testing

If you’ve ever worked with APIs, you’ve heard of Postman. It’s the tool that turns “let me write a curl command and pray” into a proper, repeatable workflow — send requests, inspect responses, save them, automate them, and even document your API for others.

This is a full walkthrough — setup, every major feature, and how it all fits together. 👇

📸 About the images: I’ve created 3 custom diagrams below (anatomy of a request, the request/response cycle, and environments) — download these and upload them to Medium at the marked spots. For the remaining 📸 notes, those are Postman’s own UI — take a quick screenshot yourself as you go (it’s your software, no copyright issue) and drop it in.

— -

## 🧰 What Is Postman?

Postman is an API client — software that lets you send HTTP requests (GET, POST, PUT, DELETE, etc.) to any API and see exactly what comes back, without writing any code.

Think of it as a remote control for APIs:

• Build a request visually (URL, headers, body, auth)

• Send it

• See the response (status code, headers, body, time taken)

• Save it, organize it, share it, automate it

🧠 My take: Before Postman, this meant curl commands or writing throwaway code just to test an endpoint. Postman replaced both — and added a UI good enough that entire teams now write their API docs inside it.

— -

## ⚙️ Setup

1. Go to postman.com/downloads and download the desktop app for your OS (Windows/Mac/Linux). A browser version also exists, but the desktop app has more features (and works offline).

2. Install and open it.

3. Create a free account — this syncs your collections across devices and is required for most collaboration features.

4. You’ll land on the Home screen, with a sidebar for Collections, Environments, APIs, and more.

📸 Screenshot idea: The Postman home screen right after signing in — sidebar visible.

— -

## 🗺️ The Interface — A Quick Tour

When you create a new request, you’ll see:

• Method dropdown → GET, POST, PUT, PATCH, DELETE, etc.

• URL bar → where the endpoint goes

• Tabs below the URL → Params, Authorization, Headers, Body, Pre-request Script, Tests, Settings

• Send button → fires the request

• Response panel (bottom/right) → shows the body, status code, time, size, headers, and cookies of the response

🧠 My take: The tab row is the heart of Postman. Every concept from the REST API article (headers, params, body, auth) maps to one of these tabs — Postman is basically a visual builder for an HTTP request.

— -

## 📨 Sending Your First Request

1. Click New → HTTP Request (or the + tab).

2. Set the method to GET.

3. Paste a public API URL, e.g. https://jsonplaceholder.typicode.com/users/1.

4. Click Send.

5. The response panel shows:

• Status: 200 OK (color-coded — green for 2xx, red for 4xx/5xx)

• Time: how long the request took

• Size: response size

• Body: the actual JSON — Postman pretty-prints and color-codes it

Example: This is the same as running curl [https://jsonplaceholder.typicode.com/users/1](https://jsonplaceholder.typicode.com/users/1`) — but with a readable, formatted, searchable response instead of a wall of text in your terminal.

📸 Screenshot idea: Response panel showing 200 OK in green, response time (e.g. 312 ms), size, and the pretty-printed JSON body.

— -

## ❓ Query Params Tab

Add key-value pairs that get appended to the URL automatically.

• Go to the Params tab

• Add key: category, value: shoes

• Postman automatically updates the URL to ?category=shoes

Example: Add page: 2 and limit: 20 → URL becomes /products?page=2&limit=20 without you typing the ? and & yourself.

🧠 My take: This tab is great for experimenting — toggle params on/off with the checkbox next to each one without deleting them, so you can quickly test “with vs without this filter.”

— -

## 🏷️ Headers Tab

Add any custom headers your API needs.

• Common ones: Content-Type: application/json, Authorization: Bearer <token>, Accept: application/json

• Postman auto-adds some headers (like User-Agent, Accept-Encoding) — these show in a grayed-out “auto-generated” section you can still view/override.

📸 Screenshot idea: Headers tab with Content-Type and Authorization manually added, plus the collapsed “hidden auto-generated headers” section.

🧠 My take: If your API call works in the browser but fails in Postman (or vice versa), compare headers first — especially Content-Type and Authorization. That mismatch is the #1 cause of “it works everywhere except here.”

— -

## 🔐 Authorization Tab

Instead of manually adding an Authorization header every time, use this tab — Postman builds the header for you.

Supported types include:

• No Auth

• Bearer Token → just paste your token, Postman adds Authorization: Bearer <token>

• Basic Auth → username/password, Postman base64-encodes it automatically

• API Key → choose header or query param placement

• OAuth 2.0 → Postman can run the entire OAuth flow for you and fetch a token

Example: Paste your JWT into Bearer Token, and every request in this tab automatically includes Authorization: Bearer eyJhbGc… — no manual header needed.

📸 Screenshot idea: Authorization tab with “Bearer Token” selected and a token pasted in, showing the auto-generated header preview below.

🧠 My take: The OAuth 2.0 tab is a huge time-saver — Postman can literally open a browser window, let you log in, and capture the access token automatically. Worth setting up once per API rather than manually copy-pasting tokens.

— -

## 📦 Body Tab

Where you set the request body for POST, PUT, PATCH requests.

Options:

• none → no body

• form-data → for file uploads / multipart forms

• x-www-form-urlencoded → traditional HTML form encoding

• raw → most common for APIs — paste JSON, XML, or plain text (set the dropdown to JSON for syntax highlighting)

• GraphQL → a dedicated mode for GraphQL queries + variables

Example: Select raw + JSON, then type:

{

“name”: “Maya”,

“email”: “maya@example.com”

}

Hit Send on a POST /users → server responds 201 Created with the new user.

📸 Screenshot idea: Body tab set to “raw” + “JSON” dropdown, with a sample JSON payload typed in, syntax-highlighted.

— -

## 🧪 Tests Tab — Writing Assertions

The Tests tab lets you write JavaScript that runs after the response comes back, to automatically check if things are correct.

pm.test(“Status code is 200”, function () {

pm.response.to.have.status(200);

});

pm.test(“Response has a user id”, function () {

const json = pm.response.json();

pm.expect(json.id).to.be.a(“number”);

});

After sending the request, a Test Results tab appears showing ✅/❌ for each assertion.

Example: You’re testing a login endpoint — write a test that checks status === 200 AND that the response body contains a token field. Now every time you hit Send, you instantly know if login is broken.

📸 Screenshot idea: Test Results tab showing 2 green checkmarks next to passing test names.

🧠 My take: This is where Postman stops being “just a request tool” and becomes a lightweight testing tool. Teams often build entire regression suites this way before investing in heavier test frameworks.

— -

## ⚡ Pre-request Script Tab

JavaScript that runs before the request is sent — used to set up dynamic values.

pm.environment.set(“timestamp”, Date.now());

Example: Generate a fresh timestamp or a random ID before each request, so you’re not hardcoding values that go stale.

— -

## 🗂️ Collections — Organizing Your Requests

A Collection is a folder of saved requests. Instead of re-typing URLs every time:

1. Click Save on any request

2. Create a new collection (e.g. “My API — v1”)

3. Organize requests into folders within it (e.g. “Auth”, “Users”, “Orders”)

Example: A collection called “E-commerce API” with folders Auth/ (login, register, refresh), Products/ (list, get, create), Orders/ (create, get, cancel) — your entire API, organized and reusable.

📸 Screenshot idea: Left sidebar showing a collection expanded into folders, each folder expanded into individual saved requests.

🧠 My take: Collections are also Postman’s “documentation” feature — click Share → View in web and Postman auto-generates a readable API doc from your saved requests. Many companies publish their public API docs this way without writing a single line of documentation manually.

— -

## 🌎 Environments & Variables

Instead of hardcoding URLs and tokens, use variables.

1. Click the Environments tab in the sidebar → + to create one (e.g. “Local”, “Staging”, “Production”)

2. Add variables like:

• base_url = http://localhost:3000

• token = <your dev token>

3. In your requests, use {{base_url}}/users instead of the full URL

4. Switch environments using the dropdown in the top-right corner

Example: Same collection, same requests — switch the environment dropdown from “Local” to “Production”, and every {{base_url}} instantly points to your live API instead of localhost. No editing requests at all.

🧠 My take: This is the single biggest “aha” moment for new Postman users. Once you set this up, you stop copy-pasting URLs and tokens between requests — and stop accidentally testing against production when you meant to test locally.

— -

## 🏃 Collection Runner — Automation

Run an entire collection (or folder) of requests in sequence, automatically.

1. Right-click a collection → Run collection

2. Choose which requests to include, how many iterations, and delay between requests

3. Click Run — Postman fires every request in order and shows pass/fail for each Tests-tab assertion

Example: Run your whole “Auth → Create User → Get User → Delete User” flow with one click, and see a summary: 4/4 requests passed, all tests green.

📸 Screenshot idea: Collection Runner results screen — a list of requests with green checkmarks and response times next to each.

🧠 My take: This is essentially free integration testing. Combine it with environment variables (run the same collection against Local, then Staging, then Production) to catch environment-specific bugs early.

— -

## 🎭 Mock Servers

Postman can simulate an API that doesn’t exist yet (or isn’t ready) — useful when frontend and backend teams are working in parallel.

1. From a collection, click Mock Collection

2. Postman generates a fake URL that returns example responses you’ve saved on each request

3. Frontend devs can build against this mock URL before the real backend is finished

Example: Backend team hasn’t built /products yet — frontend team points at the mock server, which returns a saved example JSON response, letting UI development continue in parallel.

— -

## 📖 API Documentation

Every collection can be turned into shareable, readable documentation automatically.

1. Click the collection → View Documentation (or the </> icon)

2. Postman generates a page showing every request, its parameters, headers, body, and example responses

3. Click Publish to get a public URL — or keep it private for your team

Example: Stripe, Twilio, and many other companies’ public docs are partly built this way — generated directly from a maintained Postman collection.

📸 Screenshot idea: The auto-generated documentation view — a request shown with its description, example request, and example response side by side.

— -

## 👥 Team Collaboration & Workspaces

• Workspaces → shared spaces where a team’s collections, environments, and APIs live together

• Changes sync in real-time — like Google Docs for API collections

• Comments → leave notes on specific requests for teammates

• Forking → copy someone else’s collection into your own workspace to experiment without affecting the original

🧠 My take: If you’re working solo, a personal workspace is fine. The moment more than one person touches the same API, a shared team workspace pays for itself almost immediately — no more “which Postman collection is the latest one?” in Slack.

— -

## 🤖 Newman — Running Collections via CLI/CI

Newman is Postman’s command-line companion — it runs a collection (and its tests) from the terminal, so you can plug it into CI/CD pipelines.

npm install -g newman

newman run my-collection.json -e my-environment.json

Example: Add this to your GitHub Actions workflow so every pull request automatically runs your API test collection — if any test fails, the build fails.

— -

## ⌨️ Useful Shortcuts & Tips

• Ctrl/Cmd + S → Save request

• Ctrl/Cmd + Enter → Send request

• Ctrl/Cmd + Alt + C → Generate code snippet (cURL, JavaScript, Python, etc.) for the current request — great for handing off to developers

• Console (bottom-left icon) → see the raw request/response, exactly as sent — invaluable for debugging headers that “should” be there but aren’t

📸 Screenshot idea: The “Generate Code” panel showing the same request as a cURL command, a JavaScript fetch, and a Python requests snippet.

— -

## 🎯 Putting It All Together — A Typical Workflow

1. Create an Environment with base_url and token variables

2. Build requests using {{base_url}} — set up Auth, Headers, Body as needed

3. Add Tests to each request to catch regressions

4. Organize everything into a Collection with folders

5. Use the Collection Runner to test the full flow end-to-end

6. Publish documentation so others can use your API

7. Optionally run the collection via Newman in CI on every code change

That’s the full loop — from “manually testing one endpoint” to “automated, documented, team-shared API testing.”

— -

### 💬 Final Thought

Postman looks simple on the surface — send a request, see a response — but every tab and feature maps to a real problem teams run into: managing secrets (environments), catching regressions (tests), onboarding new devs (docs), and automating checks (Runner/Newman).

Set up one environment and one test today — future-you will thank present-you the next time an API “randomly” breaks. 🔖

— -

👏 If this helped, drop a clap and follow — more practical dev tool breakdowns coming!