Glossary

Postman

Postman helps prepare, send, and repeatedly verify API requests. It is not the API itself, the authoritative specification for every interface, or a replacement for server-side validation.

Short definition

An API client extended with collections, scripts, and collaboration.

An API is an interface exposed by a running application. Postman is a client and workspace in which a developer sets the method, URL, headers, authorisation, and optional request body, sends the request, and inspects the response.

Postman is more than a desktop application: it also offers a web app, a VS Code extension, and Postman CLI. For some requests and local-network access, the web version may need a suitable Postman Agent, and feature availability depends on the chosen product and plan.

The problem it solves

Turns a request into a repeatable, shareable workflow.

curl can send a one-off request. Postman becomes useful when requests need to be assembled comfortably, grouped, moved between environments, and rerun with response checks.

explore an endpoint manually while developing a PHP backend or integrating a third-party service
organise authentication, product, and order requests into a readable sequence
run the same collection against local, test, and other authorised environments
verify status codes, headers, and selected response fields with post-response scripts
run selected collections in CI/CD through Postman CLI and publish accessible API documentation

Practical example

A collection for an online shop’s order flow

The collection contains a folder with four requests: authentication, product retrieval, order creation, and order-detail retrieval. Each URL begins with the baseUrl variable. Credentials and production tokens stay outside the collection. A manual local run can use Local Vault; CLI or cloud runs can use Shared Vault where supported, an approved external secrets manager, or a token injected securely from a protected CI secret.

Authorisation can be configured at folder or collection level and inherited by requests. After the order is created, a short post-response script validates the response and saves only the new ID in the orderId variable. The final request then calls GET {{baseUrl}}/orders/{{orderId}}. Automated runs belong in an isolated test environment, not against real production customers without deliberate safeguards.

JavaScript / Post-response script

pm.test('Order was created', () => {
  pm.response.to.have.status(201);

  const order = pm.response.json();
  pm.expect(order.id).to.be.a('string').and.not.empty;
  pm.environment.set('orderId', order.id);
});

How it works

Request → response → check → pass a value to the next step.

Postman keeps request configuration separate from values that change with the environment or each run.

Build the request The developer selects an HTTP method, URL, query parameters, headers, body, and authorisation scheme according to the API contract.
Resolve variables Postman resolves variables according to their scope. An environment can switch baseUrl; sensitive values stay separate from the collection through Local Vault for manual local runs or, where available, Shared Vault or a securely injected CI secret for automation.
Send and receive The selected agent sends the request to the server. Postman displays the status, headers, body, cookies, and response time; a successful status alone does not prove that the business outcome is correct.
Post-response script JavaScript using the pm object checks expected response properties and can save a value, such as the order ID, for the next request.
Repeat the run Collection Runner or Postman CLI runs a collection or folder in the specified sequence and reports the checks interactively or in CI.

Key concepts

Requests, collections, and values have distinct responsibilities.

A well-organised workspace makes each request’s purpose clear without copying credentials and addresses between steps.

HTTP request

The method expresses the intended operation, the URL identifies the target, headers carry metadata, and the body carries data. Postman provides editors for JSON, forms, and files, but the API always determines the correct format.

Collections and folders

A collection is a portable structure of requests, examples, variables, and scripts. Folders divide a larger flow by feature or scenario and can share authorisation or scripts with their children.

Environments and variables

An environment groups values for a particular deployment environment. Narrower and broader scopes also exist; when names collide, precedence decides which value wins, so each variable’s ownership should be obvious.

Authentication and authorisation

Authentication can use an API key, Bearer token, Basic Auth, or OAuth 2.0, for example. Postman prepares the relevant part of the request, but the server must always enforce authorisation for the action.

Scripts and tests

A pre-request script prepares the run; a post-response script checks the result. A test can verify a status code, header, or specific JSON field and pass output to the next step.

Workspaces and documentation

A workspace organises collections, environments, specifications, mocks, and other team resources. Postman can display or publish documentation from a collection; examples and shared values must be reviewed before publication.

Benefits, limitations, and common mistakes

Fast feedback helps when the contract and security remain intact.

Benefits

build a clear request without assembling a long command by hand
create a repeatable scenario with variables and response checks
share documented requests and examples in a team workspace
run the same collection manually or automate it through the CLI
import an OpenAPI specification as a starting point for exploration and tests

Limitations and common mistakes

storing production credentials directly in a shared collection, environment, example, or published documentation
treating one successful manual request as proof that every error and concurrency scenario works
relying on a handful of Postman tests as an automatic replacement for the backend’s full integration-test layer
leaving baseUrl, a token, or orderId in the wrong scope and accidentally using it against another environment
publishing a collection without reviewing example responses and sensitive headers

Practical use and comparison

Postman complements the contract and backend tests; it does not replace them.

REST API is one approach to interface design over HTTP. Postman can send requests to it, but supports other interface types too and does not enforce a RESTful design. It can reveal an incorrect method, unstable URL, or inconsistent response, but cannot repair the architecture.

OpenAPI is a standardised, machine-readable description of an HTTP API. A Postman Collection is a set of executable requests, examples, and workflows. Postman can import OpenAPI, generate a linked collection, and subsequently synchronise the pair. An arbitrary collection is not automatically linked, and the two artefacts remain distinct. The team must choose the authoritative contract source and keep it current.

A Postman test is useful for checking observable responses and a sequence of several requests. Backend integration tests can additionally prepare state directly and verify the database, queue, or transactions in isolation. The right combination depends on risk: Postman provides a consumer view of the API, while the application test suite verifies its internal guarantees.

A mock server can return predefined responses from saved examples while the real backend is unavailable. It is useful for temporarily decoupling client and server work, not as evidence of actual validation, permissions, performance, or database behaviour.

Implementation checks

A collection should be safe, readable, and repeatable.

Before sharing or automating a collection, verify where values come from, where requests are going, and what each test actually proves.

name requests by operation and scenario, and group them into short, understandable folders
use baseUrl and environments explicitly so a test run cannot accidentally target production
use Local Vault for manual local runs; for CLI or cloud runs, use Shared Vault where available, an external secrets manager, or a protected CI secret—never a shared collection
check not only 2xx responses but also the response structure and expected safe failure scenarios
version an export or Git-connected source when a collection is part of automated verification
keep the documentation and collection aligned with the authoritative API contract

Common questions

Postman without common misconceptions

Is Postman an API?

No. Postman is a client and platform for working with APIs. The API itself is provided by a server or another target service.

Does a Postman Collection replace an OpenAPI specification?

No. A collection describes executable requests and workflows; OpenAPI defines a standardised HTTP interface contract. The two can be generated or synchronised, but the team must choose an authoritative source.

Where should a production token be stored?

Not directly in a shared collection. A manual local run can use Local Vault; a CLI or cloud run can use Shared Vault where available, an external secrets manager, or a protected CI secret with restricted access and rotation.

Do Postman tests replace backend integration tests?

Not automatically. They are effective at checking HTTP behaviour and user flows, but do not cover every transaction, concurrency case, queue, database change, or server-side security boundary on their own.

Is Postman only a desktop application?

No. A web app, VS Code extension, and Postman CLI are also available. Some web scenarios need a Postman Agent, and feature availability differs between products.

Hands-on experience

I assess an API request as part of the complete integration flow.

For online shops and backend integrations, I connect the contract, authentication, failure cases, automated checks, and safe handling of sensitive data.

How I work with APIs and integrations Discuss your project