Postman Guide

Volume 3 — Modern Development

Postman is the standard tool for manually exercising an API outside the application that normally calls it — exactly the kind of ad hoc testing that happens constantly while building out RoundTrip and Waypoint endpoints. This closes out Volume 3.

1. Requests and Collections

A request is a single saved API call — method, URL, headers, body, auth. A collection is a folder of related requests, organized to mirror your actual API structure.

RoundTrip API
├── Auth
│   └── Login
├── Leave Requests
│   ├── List Leave Requests
│   ├── Create Leave Request
│   ├── Approve Leave Request
│   └── Cancel Leave Request
└── Team Management
    ├── List Team Members
    └── Get Weekly Schedule

Organizing by resource (mirroring the REST API chapter's resource-based URL structure) rather than by "requests I made this week" keeps a collection navigable as it grows — the alternative degrades into an unsearchable pile within a few weeks of active development.

2. Environments and Variables

An environment is a named set of variables — the mechanism that lets the exact same collection run against dev, staging, or production without editing a single request.

Environment: RoundTrip - Development
  base_url = https://dev.api.roundtrips.app
  auth_token = (blank, filled after login)

Environment: RoundTrip - Production
  base_url = https://api.roundtrips.app
  auth_token = (blank, filled after login)

Requests reference variables with double curly braces:

GET {{base_url}}/leave-requests
Authorization: Bearer {{auth_token}}

Switching the active environment in the top-right dropdown changes every request's behavior instantly, with zero edits to the requests themselves. This is the single habit that separates a maintainable Postman setup from one where half the requests still have a hardcoded dev URL nobody remembers to update.

3. Authentication

For bearer-token auth (the pattern used across Traxs APIs — see the Authentication & Authorization chapter):

1. Open a request's Authorization tab.
2. Set type to Bearer Token.
3. Enter {{auth_token}} as the value, referencing the environment variable rather than pasting a raw token directly into the request.

Setting the token automatically after login, rather than copy-pasting it manually every time it expires, via a Tests script on the login request:

const response = pm.response.json();
pm.environment.set("auth_token", response.accessToken);

This runs automatically every time the login request executes, writing the returned token straight into the environment variable every other request already references — after this, re-authenticating is just re-running one request, not manually copying a token around.

4. Test Scripts

The Tests tab runs JavaScript after a response arrives — useful for quick sanity checks well beyond just capturing a token:

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

pm.test("Response has expected fields", function () {
    const body = pm.response.json();
    pm.expect(body).to.have.property("id");
    pm.expect(body).to.have.property("status");
});

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

These tests run every time the request executes, in the Postman UI directly, and are what a Collection Runner pass (Section 6) actually reports pass/fail against — not just a manual glance at the response body.

5. Pre-request Scripts

The Pre-request Script tab runs before the request is sent — useful for computing a value the request needs, like a timestamp-based signature, or refreshing a token proactively if it's close to expiring:

const tokenExpiry = pm.environment.get("token_expiry");
if (!tokenExpiry || Date.now() > tokenExpiry) {
    console.log("Token expired or missing — re-run the Login request first");
}

6. Collection Runner and Newman

The Collection Runner (Runner button, top of the Postman window) executes every request in a collection in sequence, running all their Tests scripts, and reports a pass/fail summary — useful for a quick smoke test across an entire resource area (every Leave Request endpoint, for example) after a deploy.

Newman is Postman's command-line runner — the same collection, executed outside the GUI, which is what makes Postman collections usable inside a CI/CD pipeline rather than only as a manual desktop tool:

npm install -g newman
newman run RoundTrip-API.postman_collection.json -e RoundTrip-Development.postman_environment.json

This is the bridge between "I tested this manually in Postman" and "this is now an automated check that runs on every deploy" — directly relevant to the automated testing infrastructure work (WAY-39) as an option worth considering for smoke-testing critical endpoints post-deploy, distinct from proper unit/integration test coverage.

7. Sharing Collections

Method	Use case
Export as JSON	A portable file, committed to the repo or shared directly — the simplest option for a small team
Postman Team Workspace	Live-syncing shared collections, requires a paid/team Postman account
Fork/pull within a workspace	Team members work from a shared base collection without directly overwriting each other's changes

For a small team, committing exported collection and environment JSON files directly into the repo (in a postman/ folder, alongside the API project) keeps them versioned with the code they test, without depending on a separate paid service.

8. Troubleshooting Playbook

Symptom	Likely cause	What to check
{{base_url}} shows up literally in the request, unresolved	No environment is active, or the variable name doesn't match exactly	Confirm an environment is selected in the top-right dropdown; check for a typo in the variable name
401 on every request despite having logged in	Token wasn't actually saved to the environment variable	Check the login request's Tests script actually ran and set auth_token; check the environment's current variable value directly (eye icon)
SSL/certificate error only in Postman, not in the browser	Postman has its own certificate trust store, separate from the OS/browser	Check Postman's Settings → Certificates; for local self-signed dev certs, this often needs a separate explicit trust entry
Request works standalone, fails when run via Collection Runner	Runner executes requests in sequence and shares environment state — an earlier request in the sequence may have failed to set something a later one depends on	Check the Runner's per-request results in order, not just the final summary
Variable value from one environment "leaking" into another	Global variables (as opposed to environment-scoped ones) are shared across every environment regardless of which is active	Confirm whether a value was set as Global vs. Environment-scoped — Global overrides silently if not intended
Body not being sent, or sent as the wrong content type	Body tab set to the wrong mode (form-data vs. raw JSON), or Content-Type header not matching the actual body format	Confirm Body tab is set to raw + JSON, and the Headers tab isn't manually overriding Content-Type to something inconsistent

9. Quick Reference

Category	Item	Detail
Structure	Collection	A folder of related requests
Structure	Environment	A named set of variables, switchable per request context
Variables	{{variable_name}}	Reference syntax used in URLs, headers, bodies
Auth	Bearer Token	Set type in Authorization tab, reference {{auth_token}}
Automation	Tests tab	JavaScript run after the response, pm.test(...) assertions
Automation	Pre-request Script	JavaScript run before the request is sent
Automation	pm.environment.set(...)	Write a value into the active environment from a script
CLI	Newman	Command-line collection runner, usable in CI/CD
Sharing	Export as JSON	Simple, versionable, no paid account required
Debug	Console (bottom-left)	Shows the raw request/response and any console.log output from scripts

---

Part of the Traxs Engineering Handbook — Volume 3: Modern Development. Companion chapters in this volume: Docker Fundamentals, Docker Compose, REST APIs, Authentication & Authorization, JSON & YAML.

Volume 3 — Modern Development is now complete: Docker Fundamentals, Docker Compose, REST APIs, Authentication & Authorization, JSON & YAML, and Postman Guide.