Topic 3: Postman Configuration

📖 6 min read · 🎯 beginner · 🧭 Prerequisites: react-structure, php-with-select-fetch

Why this matters

You've built your API routes in Express — the endpoints exist, the logic is there. But here's the thing — how do you actually test them without building a full frontend first? Every time you make a change, do you spin up a React app just to check if a route returns the right data? That's slow, fragile, and honestly exhausting. Postman solves exactly this. It lets you fire real HTTP requests at your server, inspect every detail of the response, and set up automated checks — all without touching your app code. It's the tool professionals use every single day, and once you try it, you won't go back.

What You'll Learn

• Install Postman and create your first GET and POST requests
• Organize requests into Collections for repeatable, shareable workflows
• Use Environment Variables to switch between localhost, staging, and production with one click
• Write JavaScript test scripts that automatically validate status codes, response times, and headers
• Run a full Collection via the Collection Runner to automate an entire API test suite

The Analogy

Think of Postman as a fully equipped post office for your API. When you want to know whether a particular address (endpoint) actually receives mail (requests) and sends back the right reply (response), you don't trust a stranger to deliver it — you walk it there yourself, hand it over the counter, and read the receipt on the spot. Collections are your sorted mailbag for a whole route, environment variables are the address book you swap out when you move from the development neighborhood to the production district, and test scripts are the quality-control checklist the clerk runs before stamping "Delivered."

Chapter 1: Introduction to Postman

Postman is a powerful API client that lets you create, send, inspect, and automate HTTP requests — all through a graphical interface, no curl memorization required.

Key Features of Postman

1. Creating Requests — Easily configure and send any HTTP method: GET, POST, PUT, DELETE, PATCH, and more.
2. Inspecting Responses — View the full response: status code, headers, body, and response time in a single pane.
3. Collections — Group related requests into named collections for better organization and sharing.
4. Environment Variables — Define variables (like baseUrl) once per environment and reuse them across every request.
5. Testing and Automation — Write JavaScript test scripts that run automatically after each request; chain them into automated workflows.

Chapter 2: Installing Postman

Step 1: Download and Install Postman

Download and install Postman from the official website: https://www.postman.com/downloads/

Choose the installer for your operating system (macOS, Windows, or Linux), run it, and launch Postman. Create a free account or skip sign-in to use the tool locally.

Chapter 3: Creating a GET Request

Step 1: Open Postman and Create a New Request

1. Open Postman.
2. Click the New button and select Request.
3. Enter a name for the request — for example, Get Books — and click Save to Collection (create a new collection if prompted).

Step 2: Configure and Send the Request

1. Set the request method dropdown to GET.
2. Enter the request URL — for example:

http://localhost:3000/books

3. Click the Send button.

Postman displays the full server response: the HTTP status code (e.g., 200 OK), all response headers, and the response body. You can toggle between Pretty, Raw, and Preview views for the body.

Chapter 4: Creating a POST Request

Step 1: Create a New Request

1. Click the New button and select Request.
2. Name it Add Book and save it to your collection.

Step 2: Configure the POST Request

1. Set the method dropdown to POST.
2. Enter the request URL:

http://localhost:3000/books

3. Open the Body tab, select raw, and choose JSON from the format dropdown on the right.
4. Enter the JSON payload for the new resource:

{
    "title": "To Kill a Mockingbird",
    "author": "Harper Lee"
}

5. Click Send.

Postman displays the server's response — including the status code (e.g., 201 Created), response headers, and the body confirming the newly created resource.

Chapter 5: Using Collections

Collections keep related requests organized and make it easy to share or re-run an entire API surface area.

Step 1: Create a Collection

1. Click New and select Collection.
2. Enter a name — for example, Book API — and click Create.

Step 2: Add Requests to the Collection

1. Drag and drop existing requests into the collection in the left sidebar.
2. Or create new requests directly inside the collection by right-clicking it and selecting Add Request.

Collections can also hold folders, letting you group requests by resource (e.g., /books, /authors) or by operation type (reads vs. writes).

Chapter 6: Using Environment Variables

Environment variables let you swap configuration values — like your base URL — without editing every request manually.

Step 1: Create an Environment

1. Click the gear icon (⚙️) in the top-right corner and select Manage Environments.
2. Click Add to create a new environment.
3. Name it Development.
4. Add a variable: set Variable to baseUrl and Initial Value (and Current Value) to http://localhost:3000.
5. Click Add to save the environment.

Step 2: Use Environment Variables in Requests

1. Replace the hardcoded base URL in your request URLs with the variable notation:

{{baseUrl}}/books

2. Select Development from the environment dropdown in the top-right corner of Postman.
3. Click Send.

Postman substitutes {{baseUrl}} with http://localhost:3000 at send time. To switch to staging, create a Staging environment with a different baseUrl value and select it from the same dropdown — all your requests update instantly.

Chapter 7: Writing Tests

Postman's Tests tab lets you write JavaScript assertions that run automatically after every request, so you catch regressions the moment an endpoint misbehaves.

Step 1: Add Tests to a Request

1. Open any saved request and navigate to the Tests tab.
2. Enter test scripts using the pm object. For example:

pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

pm.test("Response time is less than 500ms", function () {
    pm.expect(pm.response.responseTime).to.be.below(500);
});

pm.test("Content-Type is application/json", function () {
    pm.response.to.have.header("Content-Type", "application/json");
});

3. Click Send.

Postman runs each pm.test callback immediately after the response arrives and displays the results in the Test Results tab at the bottom — green for pass, red for fail.

Chapter 8: Automating Workflows with Postman

The Collection Runner lets you execute an entire collection of requests in sequence — complete with test assertions — in a single automated run.

Step 1: Create a Collection for Automation

1. Click New → Collection.
2. Name it Book API Tests and click Create.

Step 2: Add Requests to the Collection

1. Add all your requests (e.g., Get Books, Add Book) to the collection.
2. For each request, add pre-request scripts (under the Pre-request Script tab) if setup logic is needed, and add test assertions under the Tests tab.

Step 3: Run the Collection

1. Click on the collection name in the sidebar to open its detail view.
2. Click the Run button (▶) to open the Collection Runner.
3. Configure the run options:
   • Select the Environment (e.g., Development)
   • Set the Iteration count if you want to repeat the run multiple times
4. Click the Run Book API Tests button.

Postman executes each request in sequence, runs its tests, and displays a full summary: requests sent, tests passed, tests failed, and total run time.

flowchart TD
    A[Collection Runner starts] --> B[Request 1: GET /books]
    B --> C{Tests pass?}
    C -- Yes --> D[Request 2: POST /books]
    C -- No --> E[Mark FAILED, continue]
    D --> F{Tests pass?}
    F -- Yes --> G[Run complete — all green]
    F -- No --> H[Mark FAILED, end report]

🧪 Try It Yourself

Task: Wire up a two-request collection that tests your local books API end-to-end.

1. Make sure a local server is running at http://localhost:3000 (use the PHP + fetch server from the previous lesson, or any Express/JSON-server setup).
2. Create an environment named Dev with baseUrl = http://localhost:3000.
3. Create a collection named Books Smoke Test.
4. Add a GET request to {{baseUrl}}/books with this test script:

pm.test("Status is 200", function () {
    pm.response.to.have.status(200);
});
pm.test("Body is an array", function () {
    const json = pm.response.json();
    pm.expect(json).to.be.an("array");
});

5. Add a POST request to {{baseUrl}}/books with body:

{
    "title": "Clean Code",
    "author": "Robert C. Martin"
}

and test:

pm.test("Book was created", function () {
    pm.response.to.have.status(201);
});

6. Open the Collection Runner, select Dev, and hit Run.

Success criterion: Both requests show green in the Test Results panel and the runner summary reads 2/2 tests passed.

🔍 Checkpoint Quiz

Q1. What is the purpose of Environment Variables in Postman?

A) To store your Postman account password
B) To define reusable values (like a base URL) that can be swapped per environment without editing each request
C) To set Node.js environment variables on your server
D) To configure headers that Postman adds automatically to every request

Q2. Given this Postman test script, what happens if the server responds with a 404 status?

pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

A) Postman throws a JavaScript error and halts
B) The test is skipped
C) The test is marked as failed in the Test Results panel
D) Postman automatically retries the request

Q3. You have 15 saved requests spread across a Book API collection. You want to run all of them in order against your staging server. Which Postman feature handles this in a single click?

A) Environments panel
B) Pre-request Script tab
C) Collection Runner
D) Postman Monitor

Q4. A colleague shares a Postman collection export. Your baseUrl is http://localhost:3000 but theirs was https://api.staging.example.com. Without changing any request URLs, how do you run their collection against your local server?

A1. B — Environment Variables let you define values like baseUrl once per environment. Switching the active environment updates every {{baseUrl}} reference across all requests instantly.

A2. C — The pm.response.to.have.status(200) assertion evaluates to false for a 404 response. Postman marks the test failed and highlights it in red in the Test Results panel, but continues running subsequent tests.

A3. C — The Collection Runner executes every request in a collection sequentially, runs their test scripts, and produces a pass/fail summary for the whole run.

A4. Create a new environment (e.g., Local) with a variable baseUrl set to http://localhost:3000. As long as the collection's request URLs use {{baseUrl}}, selecting your Local environment from the dropdown before running means Postman substitutes your value — no request editing required.

🪞 Recap

• Postman is an API client for sending HTTP requests and inspecting responses without writing any application code.
• Collections group related requests and can be run in sequence via the Collection Runner for automated API testing.
• Environment Variables (e.g., {{baseUrl}}) decouple configuration from requests, making environment switching a one-click operation.
• The Tests tab accepts JavaScript (pm.test, pm.expect) assertions that run automatically after each response.
• The Collection Runner executes all requests in a collection in order, aggregating pass/fail results into a single report.

📚 Further Reading

• Postman official docs — the source of truth on every Postman feature
• Postman JavaScript test scripts reference — full pm API for assertions and pre-request logic
• Environment and variable management — scoped variables, global vs. environment vs. collection variables
• ⬅️ Previous: PHP with Select Fetch
• ➡️ Next: React Components