Postman

Why it matters

It's most teams' default for manually exploring and debugging an API

Before writing a single automated test, most developers reach for Postman (or a similar client) to poke at an endpoint and see what a response actually looks like, rather than reading documentation alone.

Collections turn one-off requests into something a whole team can reuse

A folder of related requests, saved with real values and organized by feature, replaces everyone re-typing the same curl command from memory or an outdated wiki page.

Built-in JavaScript scripting adds real automated checks on top of manual requests

The pm.test/pm.expect API lets you assert on a response's status, body, and headers directly inside the request that produced them, without a separate test file.

Newman lets the same collection run headlessly in CI

A collection built and debugged interactively in the GUI can be exported and run from the command line inside a pipeline, so manual exploration and automated regression checks share one source of truth.

Auto-generated docs lower the cost of sharing an API's shape with a team

Publishing a collection produces a browsable reference of every endpoint, its parameters, and example responses, without a separate documentation tool.

Requests, collections, and environments

{
  "name": "Get order",
  "request": {
    "method": "GET",
    "url": "{{baseUrl}}/orders/{{orderId}}",
    "header": [
      { "key": "Authorization", "value": "Bearer {{authToken}}" }
    ]
  }
}

Test scripts: pm.test and chaining requests

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

const body = pm.response.json();
pm.environment.set("orderId", body.id);

From the GUI to CI: Collection Runner and Newman

newman run orders-api.postman_collection.json \
  --environment staging.postman_environment.json \
  --reporters cli,junit

Where the collection actually lives

Mistakes people make here

Hardcoding a token or API key into a request instead of an environment variable

It works until that collection gets shared, exported, or synced to a team workspace, at which point the secret goes with it. A variable marked as a secret type, or Postman Vault, keeps the value out of what gets synced or shown to teammates.

Treating a folder of passing manual requests as an automated regression suite

Clicking Send on each request by hand doesn't run on every commit the way a CI-integrated test does. Without wiring the collection into Newman (or an equivalent) as part of a build, the checks catch nothing until someone remembers to click through them again.

Writing test scripts that depend on the request run immediately before them

Chaining requests through environment variables (grab an ID from one response, use it in the next) is convenient, but it means a request run out of order, in isolation, or in parallel fails for reasons that have nothing to do with the API itself.

Assuming everyone on the team is looking at the same environment values

Environments can be edited locally without syncing, depending on settings; two teammates can end up debugging against different base URLs or stale variable values without realizing their environments have drifted apart.

Never exporting collections into version control

A collection is just JSON, but if it only ever lives inside Postman's cloud with no export checked into git, there's no history of who changed a request's assertions or why — the review discipline applied to code doesn't automatically apply to a cloud-synced collection.

Strengths and trade-offs

Who needs this

Useful to almost anyone who calls an API by hand: backend developers debugging their own endpoints, frontend developers checking a contract before integrating, and manual/QA testers who aren't writing code. Teams that keep all API tests as code in the same repository as the service, run through something like REST Assured or pytest, may use Postman only for ad hoc exploration rather than as their test suite of record.

Questions about postman

Is Postman free to use?

There's a free plan for individual use, but it's limited to a single user and can't create a shared team workspace — collaboration features require a paid Solo, Team, or Enterprise plan.

Can Postman collections replace a real automated test suite?

They can get close once wired into Newman (or Postman's newer CLI) and a CI pipeline, but the test scripts run in a sandboxed JavaScript environment with fewer assertion and data-handling capabilities than a full test framework. Many teams use Postman for exploration and manual checks alongside, not instead of, a code-based suite like REST Assured or pytest.

What's the difference between Postman and Newman?

Postman is the GUI application; Newman is its original command-line collection runner, and it's still officially supported. Newman runs an exported collection the same way the app's Collection Runner would, but headlessly, which is what lets the same tests run inside a CI pipeline. Postman has more recently introduced a separate, newer Postman CLI that its own docs now lean on more heavily for CI, though Newman hasn't been deprecated.

Do I need Postman if I can already use curl?

curl is fine for a single one-off request. Postman's value shows up once there are many related, reusable requests that need to chain together, get shared with a team, or get documented, needs curl alone doesn't address well.

The primary source

• Postman Docs: overview ↗
• Postman Docs: test APIs and write scripts ↗
• Postman Docs: about plans ↗