Postman: Your API Command Centre

Build, run, and automate a complete API workflow inside Postman — from your first request to a full collection with environment variables and test scripts.

Before Postman existed, testing an API meant writing a curl command in the terminal, squinting at raw JSON output, and hoping you remembered the right flags. Some developers kept a text file full of curl snippets they'd paste and edit every time. It was tedious, fragile, and impossible to share with a teammate in any useful way.

Postman changed the entire mental model. Instead of one-off commands, you build collections — organised folders of API requests that run in sequence, carry shared variables, and generate test reports automatically. Teams at companies like Twilio, Shopify, and Atlassian use Postman to standardise how every developer on a backend team calls every endpoint, from local dev all the way to production.

What Postman Actually Is

Postman is a platform for working with APIs — building requests, running them, writing test assertions, generating documentation, and orchestrating automated runs across environments. The free tier gives you nearly everything an individual developer needs.

Think of it as a browser specifically designed for APIs. A browser sends HTTP requests when you type a URL and click links. Postman lets you craft any HTTP request — any method, any headers, any body — and inspect the full response, including status codes, timing, response size, and cookies.

Core Features at a Glance

The Postman Workflow

A Postman workflow is not just "open app, type URL, hit send." When done properly, it mirrors how you'd structure actual integration tests — with environments that mirror real infrastructure and assertions that catch regressions before a human does.

Step 1 — Setting Up Your Workspace and Environments

A Workspace in Postman is a shared space for your team's collections, environments, and APIs. Think of it like a GitHub repository — but for API requests. The APIForge Backend team has one workspace that every engineer accesses, so there's one source of truth for how every endpoint should be called.

An Environment is a named set of variables. Instead of hardcoding https://localhost:3000 into every request, you store the base URL as a variable called {{baseUrl}}. Switch the environment from Dev to Production, and every request in the entire collection instantly targets the right server.

The APIForge Backend team needs to set up two environments: one for local development and one for their staging server. Here's exactly how those environment files look when exported as JSON — Postman can import these directly.

# WHAT: APIForge Environment config — Dev environment JSON
# Import this into Postman: Environments → Import → Paste JSON

{
  "name": "APIForge Dev",
  "values": [
    {
      "key": "baseUrl",
      "value": "http://localhost:3000",
      "type": "default",
      "enabled": true
    },
    {
      "key": "apiVersion",
      "value": "v1",
      "type": "default",
      "enabled": true
    },
    {
      "key": "authToken",
      "value": "",
      "type": "secret",
      "enabled": true
    },
    {
      "key": "teamId",
      "value": "team_abc123",
      "type": "default",
      "enabled": true
    }
  ]
}

Step 2 — Building a Collection with Real Requests

A Collection is the core unit of Postman organisation. It is a folder — or a tree of folders — containing saved HTTP requests. You can think of it as a living document of how your API actually works, except it is executable. Every request in the collection is runnable and shareable.

The APIForge Backend team organises their collection by resource: a Projects folder, a Users folder, an Auth folder, and an Integrations folder. Inside each folder are the requests for every operation — GET, POST, PUT, DELETE — each pre-configured with headers, body, and auth.

Here is the APIForge Projects collection — four key requests that cover the full CRUD lifecycle for the /projects resource. These requests use environment variables, so they work against dev or staging without any changes.

# WHAT: APIForge Projects — four CRUD requests in Postman collection
# Using {{baseUrl}} and {{apiVersion}} from active environment

--- Request 1: List All Projects ---
GET {{baseUrl}}/api/{{apiVersion}}/projects
Headers:
  Authorization: Bearer {{authToken}}
  Accept: application/json

--- Request 2: Create Project ---
POST {{baseUrl}}/api/{{apiVersion}}/projects
Headers:
  Authorization: Bearer {{authToken}}
  Content-Type: application/json
Body (raw JSON):
{
  "name": "Customer Portal Redesign",
  "team_id": "{{teamId}}",
  "visibility": "internal",
  "tags": ["frontend", "q3-2025"]
}

--- Request 3: Get Single Project ---
GET {{baseUrl}}/api/{{apiVersion}}/projects/{{projectId}}
Headers:
  Authorization: Bearer {{authToken}}

--- Request 4: Delete Project ---
DELETE {{baseUrl}}/api/{{apiVersion}}/projects/{{projectId}}
Headers:
  Authorization: Bearer {{authToken}}

Step 3 — Writing Test Scripts That Actually Catch Bugs

Most developers use Postman to send a request and eyeball the response. That is fine for exploration, but it does not scale. When you have 40 endpoints and a release on Friday, "eyeballing" is not a strategy.

Postman's test scripts run JavaScript after each response. They use a built-in assertion library called pm.test() — you write human-readable test names and assertions, and Postman reports pass or fail. These tests travel with the collection. Every engineer who runs it sees the same results.

The APIForge Backend team writes test scripts for every endpoint in their collection. Here is the complete test suite for the Projects endpoints — real assertions that would catch real regressions.

// WHAT: APIForge — Postman test scripts for GET /projects and POST /projects
// Paste these in the "Tests" tab of each request

// ── Tests for GET /api/v1/projects ─────────────────────────────────
pm.test("Status code is 200", function () {
  pm.response.to.have.status(200);
});

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

pm.test("Response has data array", function () {
  const body = pm.response.json();
  pm.expect(body).to.have.property("data");
  pm.expect(body.data).to.be.an("array");
});

pm.test("Each project has required fields", function () {
  const projects = pm.response.json().data;
  projects.forEach(function (project) {
    pm.expect(project).to.have.property("id");
    pm.expect(project).to.have.property("name");
    pm.expect(project).to.have.property("team_id");
    pm.expect(project).to.have.property("created_at");
  });
});

pm.test("Pagination meta is present", function () {
  const body = pm.response.json();
  pm.expect(body.meta).to.have.property("total");
  pm.expect(body.meta).to.have.property("page");
});

// ── Tests for POST /api/v1/projects ────────────────────────────────
pm.test("Status code is 201 Created", function () {
  pm.response.to.have.status(201);
});

pm.test("Created project has a generated ID", function () {
  const project = pm.response.json().data;
  pm.expect(project.id).to.be.a("string").that.is.not.empty;
});

pm.test("Returned name matches sent name", function () {
  const project = pm.response.json().data;
  pm.expect(project.name).to.equal("Customer Portal Redesign");
});

// Store the new project ID for downstream requests
const newId = pm.response.json().data.id;
pm.environment.set("projectId", newId);
console.log("Stored projectId:", newId);

Step 4 — Pre-request Scripts for Auth Automation

JWT tokens expire. API keys rotate. If your collection depends on a static token stored in an environment variable, it will break the moment that token dies — usually at 9 AM on a Monday before a big demo.

Pre-request scripts solve this. They run before the actual request fires. You can use them to call an auth endpoint, grab a fresh token, and store it in the environment — all automatically, every time. The APIForge team puts this script on the collection level so it runs before every protected request.

// WHAT: APIForge — Collection-level pre-request script
// Automatically fetches a fresh JWT before every protected request
// Place in: Collection → Edit → Pre-request Script tab

const tokenExpiry = pm.environment.get("tokenExpiry");
const now = Date.now();

// Only fetch a new token if the current one has expired
if (!tokenExpiry || now > parseInt(tokenExpiry)) {
  const loginRequest = {
    url: pm.environment.get("baseUrl") + "/api/v1/auth/token",
    method: "POST",
    header: {
      "Content-Type": "application/json"
    },
    body: {
      mode: "raw",
      raw: JSON.stringify({
        client_id: pm.environment.get("clientId"),
        client_secret: pm.environment.get("clientSecret"),
        grant_type: "client_credentials"
      })
    }
  };

  pm.sendRequest(loginRequest, function (err, response) {
    if (err) {
      console.error("Token fetch failed:", err);
      return;
    }

    const json = response.json();
    pm.environment.set("authToken", json.access_token);

    // Store expiry — token lasts 3600 seconds (1 hour)
    const expiresAt = Date.now() + (json.expires_in * 1000);
    pm.environment.set("tokenExpiry", expiresAt.toString());

    console.log("New token fetched. Expires in:", json.expires_in, "seconds");
  });
} else {
  console.log("Token still valid. Skipping auth request.");
}

Step 5 — Running the Full Collection

The Collection Runner is Postman's built-in test executor. Open it, select your collection, pick an environment, set the number of iterations, and click Run. Postman fires every request in sequence, runs all test scripts, and produces a report showing exactly which tests passed and which failed.

The APIForge Backend team runs their full collection before every release. It covers authentication, project CRUD, user management, and integration endpoints — 23 requests, 71 test assertions, completing in under 8 seconds against their staging server.

Step 6 — Automating with Newman in CI/CD

Postman's GUI is great for humans. But a CI/CD pipeline has no screen — it needs a command-line tool. That tool is Newman. Newman is Postman's official CLI runner. You export your collection and environment as JSON files, commit them to your repository, and Newman runs them in any shell — GitHub Actions, Jenkins, CircleCI, anywhere.

The APIForge DevOps team added Newman to their GitHub Actions pipeline. Every pull request triggers a full collection run against the staging API. If any test fails, the PR is blocked from merging. This is the same pattern Stripe and GitHub use internally to protect their APIs.

# WHAT: APIForge — Newman in GitHub Actions CI/CD pipeline
# File: .github/workflows/api-tests.yml

name: API Integration Tests

on:
  pull_request:
    branches: [main, staging]

jobs:
  api-tests:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Install Newman and HTML reporter
        run: |
          npm install -g newman
          npm install -g newman-reporter-htmlextra

      - name: Run APIForge collection against staging
        run: |
          newman run ./postman/apiforge-collection.json \
            --environment ./postman/apiforge-staging.json \
            --reporters cli,htmlextra \
            --reporter-htmlextra-export ./reports/api-test-report.html \
            --bail
        env:
          CLIENT_SECRET: ${{ secrets.APIFORGE_CLIENT_SECRET }}

      - name: Upload test report as artifact
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: api-test-report
          path: ./reports/api-test-report.html

Postman Sync vs Exported JSON — Which Should You Commit?

When Tests Fail — The Debugging Flow

A failed test in Postman is not a dead end — it is a breadcrumb trail. Postman gives you the request that failed, the response body, the exact assertion that threw, and the actual vs expected values. Here is the systematic way the APIForge team handles a failing CI run.

Postman vs the Alternatives

Postman wins on team workflows and automation. curl wins on speed for one-off checks in the terminal. Many backend engineers use both — curl to quickly poke an endpoint, Postman to build the proper test collection around it once the API is confirmed working.

Quiz