This is a working guide to Postman rather than an introduction to it. It follows a single thread from the first installed client through requests, collections, environment variables, authorisation and assertions, and ends where the value actually lands: a suite that runs unattended in a delivery pipeline and blocks a broken release.
Quick Overview
What this article covers: installing and signing in · the request and response loop · collections · environment variables · authorisation including OAuth 2.0 · assertions and bulk runs · generated documentation · shared workspaces · Newman in a pipeline · protocols beyond REST · monitors · where the tool stops.
Who this is for: testers moving into API work, developers responsible for their own endpoints, and QA leads who need their team’s manual routine to survive contact with an automated pipeline.
A note on scope. Two questions that usually open a Postman article are deliberately not answered here. What Postman is, why a project manager should care, and what business risk sloppy API testing creates are set out in what Postman is and how teams use it. Which tool belongs to which testing layer — functional, contract, performance, security — is answered in API testing tools and best practices. This article assumes both and goes straight to the mechanics.
Installing Postman and the Account That Actually Matters
Postman ships as a desktop application for Windows, macOS and Linux, and as a browser client covering almost the same surface. Start with the desktop build, for a reason that only shows up later: it reaches services on localhost and inside a private network directly, while the browser client needs a locally installed agent to do the same. Testing a service on a developer machine is the first thing most people try, and it is where the web client disappoints without warning.
Postman can be used anonymously, and that is exactly the configuration to avoid. Signing in binds the workspace to an account and synchronises collections, environments and history. The consequence is not convenience but continuity: work survives a reinstall, moves between machines, and becomes shareable. Everything described below under teamwork, documentation and monitoring is unavailable to an anonymous local client, so deciding this on day one saves rebuilding a collection later.
The Request and Response Loop You Repeat All Day
A request in Postman is assembled from parts that map onto the protocol: a method, a URL, headers, query parameters and, where the method allows it, a body. The response comes back split the same way — a status code, headers, and a body rendered as formatted JSON, XML, HTML or raw text. That loop is the whole tool in miniature; everything else is an arrangement of it.
The four methods that carry most REST traffic divide cleanly by intent. GET retrieves a representation and changes nothing, so it takes no body — pointing it at /api/customers/123 returns that customer. POST creates, and its body carries the new object, usually as JSON sent to the collection address /api/customers. PUT and PATCH update an existing resource at its own address, the first replacing the representation, the second amending part of it. DELETE removes the resource named in the URL. The semantics are not a Postman convention; RFC 9110: HTTP Semantics defines them, along with the status codes the response pane displays — a 200 for a successful retrieval, a 201 for a resource just created, a 404 for an address with nothing behind it. Read that code before the body: a friendly error message rendered inside a success status is a defect in the API, and a body-first reader will miss it.
Collections: Turning Loose Requests Into an Executable Specification
A saved request is useful once. A collection groups related requests — every endpoint touching user accounts, say — into a folder that can be nested to mirror the API’s own structure. The gain is not tidiness. Once the requests for a service live in one ordered tree, that tree describes what the service exposes, in a form a machine can execute. Everything downstream depends on it: the runner executes a collection, the documentation is generated from a collection, the pipeline invokes a collection, the monitor schedules a collection.
That is also the point at which naming stops being cosmetic. A request called new request copy 3 is invisible in a run report and worse than useless in generated documentation. One line of description per request, written when it is saved, is the difference between a collection a colleague can pick up and one only its author can read.
Environments: One Collection Across Development, Staging and Production
Every serious project runs against more than one deployment, each with its own base address and credentials. The tempting response is to duplicate the collection per deployment, which multiplies the maintenance and guarantees drift.
Postman’s answer is the environment: a named set of variables, referenced in requests as {{baseUrl}} or {{apiKey}} and resolved at send time from whichever environment is currently selected. Most teams keep at least three of them — a development environment, a staging environment and a production environment — and switch between them from a single control while the requests themselves stay untouched. Variables also exist at collection and global scope, which matters when a value belongs to the API rather than to a deployment.
One discipline belongs here and is easy to skip: secrets stored as plain environment values travel wherever the environment travels, including into a shared workspace and an export file. Marking them as secret variables keeps a token out of a place where it does not belong.
Authorisation: Where Bearer Tokens and OAuth 2.0 Stop Hurting
Almost every production API refuses anonymous callers, and reproducing an authorisation handshake by hand is where casual API testing stalls. Postman’s Authorization tab holds prepared schemes for the common cases — API key in a header or query parameter, HTTP Basic credentials, and bearer tokens attached without editing headers manually.
The case that earns the tab is OAuth 2.0. RFC 6749: The OAuth 2.0 Authorization Framework specifies an exchange in which the client obtains an access token from an authorisation server and then presents it to the resource server; performing that dance manually means juggling redirect URLs, client identifiers, scopes and expiry. Postman walks it step by step, stores the resulting token, and can refresh it when it expires. Authorisation set at collection level is inherited by every request inside, so the handshake is configured once rather than per endpoint.
Satisfying authorisation is not the same as testing it. OWASP API Security Top 10 2023 puts broken object level authorisation at the head of its list — a caller reaching another user’s data merely by changing an identifier. A request that authenticates correctly proves nothing about that; catching it takes a deliberately hostile request sent with a valid token belonging to somebody else.
Writing Assertions and Running Them in Bulk
Postman turns from a convenient client into a testing tool in the Tests tab, where each request carries a short JavaScript script that runs against the response. Typical assertions check the status code, confirm the shape of fields in the JSON body, verify a header, or compare a value against what the request expected. Nothing here is elaborate — the assertions that catch real regressions are a few lines long.
The Collection Runner then executes a whole collection in order, with the tests attached, against the selected environment, and reports which assertions passed. That is the moment a manual routine becomes repeatable: the check a person performed before a release now runs identically every time, and its result is a report rather than a memory.
Ordering deserves a thought before the run, because requests in a collection share state. A run that creates a record, reads it, updates it and deletes it works only in that sequence, and only if the identifier from the first request is written into a variable the later ones consume. Chaining through variables is what makes a collection an end-to-end scenario rather than a bag of isolated calls.
Documentation Generated From the Requests Themselves
Postman publishes documentation directly from a collection: request descriptions, parameters, example responses and code snippets, rendered as a browsable page. Because it comes from the same collection the team executes, it cannot silently describe an endpoint that no longer behaves that way — a stale example is a failing request, and a failing request gets noticed.
That is a different artefact from a formal contract. OpenAPI Specification v3.1.0 defines a machine-readable description of an API that tooling can validate against and generate clients from; Postman imports and exports that format, and the two are complementary rather than interchangeable. Generated documentation tells a human how to call the service; the specification tells a machine what the service promises — the ground on which contract testing between services is built.
Working as a Team Without Overwriting Each Other
Shared workspaces put a collection under joint ownership: backend and frontend developers, testers and analysts work on the same synchronised requests and environments instead of mailing exports around. The collaboration features borrow their shape from version control — comments on individual requests, forks for experimenting without disturbing the shared copy, and pull requests to merge a fork back after review.
The habit that makes this work is unglamorous. A fork that is never merged becomes a private divergent copy — the problem shared workspaces were meant to remove. Merging forks on the rhythm of code review keeps one collection authoritative, and that one collection is what the pipeline, the documentation and the monitors all read from.
Newman: Making the Pipeline the Gate That Counts
A suite that runs when someone remembers to open the runner is not a safety net. Newman, Postman’s command-line runner, executes a collection with an environment from a shell — all a build server needs. A pipeline step in Jenkins, GitLab CI or GitHub Actions can therefore run the API suite on every push, and a non-zero exit code from a failed assertion stops the deployment before the regression reaches users.
Two details decide whether this holds up. Secrets belong in the CI credential store and reach Newman as an environment at run time, never committed alongside the collection. And the collection has to be idempotent enough to run repeatedly against a shared test deployment — a scenario that creates a record must clean it up, or a later run fails for reasons unrelated to the code under test. Structured practice on both is the bulk of what API testing with Postman: automation and performance exists to build, because they are where self-taught suites usually break.
Beyond REST: GraphQL, WebSocket and gRPC
REST is the common case, not the only one. Postman sends GraphQL operations through a query editor with schema awareness rather than as opaque JSON strings — useful, because the GraphQL Specification, October 2021 Edition describes a single endpoint whose behaviour is driven entirely by the query document, so a plain REST view of it is close to useless. WebSocket connections can be opened and held, with messages exchanged interactively, which is the only sensible way to inspect a real-time channel. gRPC services can be invoked from a service definition, streaming calls included.
The practical value is uniformity: a team running a mixed estate keeps one client, one collection structure and one set of environments across protocols instead of learning a separate tool per transport. Combining that habit with a compiled language stack is the ground covered by REST API testing with Postman and Java.
Monitors: Checking the API After It Ships
A pipeline proves the API worked at build time. A monitor proves it works now. Postman schedules a collection to run at a chosen interval from its own infrastructure, in one or more regions, alerting the team when an assertion fails or a response exceeds a defined threshold. The tests are already written, so the marginal cost is a schedule.
A pair of boundaries is worth naming. A monitor hits the production API with real requests, so read-only scenarios are the safe default and anything that writes needs a dedicated account and cleanup. And a monitor checks availability and correctness, not capacity — it tells you the endpoint answers correctly, not how it behaves under pressure.
Where Postman Stops
Postman is a functional and integration testing tool that has grown documentation, collaboration and monitoring around that core. Sustained load simulation belongs to dedicated tools, contract verification between services is a separate discipline with its own tooling, and a security review needs an adversarial scanner and human judgement rather than an assertion library. Matching tool to layer rather than stretching one tool across all of them is the subject of the tools and best practices guide, and it is the honest end of this workflow: the moment a requirement steps outside the path described here, the answer is another tool rather than a harder configuration.
Frequently Asked Questions
Do I need to know JavaScript to use Postman?
Not for the core loop. Sending requests, reading responses, organising collections and switching environments require no programming. Writing assertions in the Tests tab does use JavaScript, but the scripts that catch real regressions are a few lines of documented assertion syntax rather than general programming.
Is the free plan enough for a small team?
The workflow described here — requests, collections, environments, tests, the runner and Newman in a pipeline — is available without a paid plan, because Newman is open source. Shared workspace capacity, monitoring volume and governance features are where paid tiers apply, so check current vendor terms against your team size rather than assuming either way.
How is running a collection in Postman different from running it with Newman?
The execution is the same; the trigger and the audience differ. The Collection Runner is interactive and reports to a person on screen. Newman runs headless, returns a non-zero exit code when an assertion fails and emits machine-readable reports — which is what lets a build server treat the result as a gate.
Where should secrets for authorisation live?
Not in the collection, and not in a plain environment value that gets exported or shared. Use secret variables locally and inject credentials from the CI credential store at run time. A token committed alongside a collection is a leaked token as soon as the repository is cloned.
Can Postman replace unit tests?
No, and treating it as though it can produces a slow, fragile suite. Postman exercises an API across the network — right for integration scenarios, wrong for verifying internal logic. Unit tests stay next to the code they cover.