Postman Tool Guide

Postman is a desktop and web application for designing, exploring, documenting, and testing APIs. Instead of typing curl commands and losing them in shell history, you build requests visually, save them, share them, and reuse them across environments. This guide covers getting started: the interface, collections, workspaces, environments, and collaboration. For writing automated assertions and running suites in CI, see the Postman API testing guide.

When to use it

Reach for Postman when you are learning a new API, debugging a failing endpoint, sharing reproducible requests with teammates, or onboarding people to a service. It is a good fit for manual exploration and team documentation.

Quick start

Download the app from the Postman website, or use the web version, and sign in. Then:

1. Click New, then HTTP, or open a new request tab.
2. Choose a method, such as GET, and enter a URL, for example https://httpbin.org/get.
3. Add query parameters in the Params tab, headers in Headers, and a body in Body.
4. Click Send and inspect the status, time, size, and response body.

The same request in curl, which Postman can generate through the code snippet button, looks like this:

curl -X POST https://httpbin.org/post \
  -H "Content-Type: application/json" \
  -d '{"name": "Ada", "role": "engineer"}'

You can also import a curl command directly with Import, which is a quick way to move a bug report into Postman.

Core concepts

• Request: method, URL, headers, authorisation, and body.
• Collection: a folder-like group of related requests, the unit you save, share, and run.
• Workspace: a space that groups collections, environments, and members. Types include personal, team, and public.
• Environment: a named set of variables, such as dev, staging, and production.
• Variable: a placeholder written with double curly braces, resolved by scope.
• History and tabs: recent requests and open work.

Environments and variables

Hardcoding https://api.dev.example.com in fifty requests is a maintenance trap. Create an environment per stage with the same variable names and different values, then reference the variable in the request URL as base_url wrapped in double curly braces.

Variables resolve from narrowest to widest scope: local, data, environment, collection, then global. Prefer collection or environment scope for most things.

Mark sensitive variables as secret type so the value is masked. Remember that the current value is local to you and is not synced, while the initial value is shared with the workspace. Put real tokens only in current value.

Authorisation

The Authorisation tab supports Bearer token, Basic, API key, OAuth 2.0, and more. Set it at the collection or folder level so requests inherit it. For OAuth 2.0, Postman can run the flow and fetch tokens for you, then refresh them.

Collaboration and documentation

Team workspaces let colleagues share collections with role-based access. Changes are tracked through forks, pull requests, and version history, so you can review edits to a collection much as you would code. Postman generates browsable documentation from collection descriptions and examples, and saved example responses double as living documentation and as mock data. A mock server can answer requests from those examples so front-end teams are not blocked on a backend.

You can also import an OpenAPI file to generate a collection:

# Import through the UI: Import, then choose openapi.yaml
# Or fetch a spec to inspect before importing
curl -O https://example.com/openapi.yaml

Common pitfalls

• Secrets in shared values. Initial values sync to everyone in the workspace, so never store credentials there.
• Collections sprawling in personal workspaces, which hides them from the team. Use a shared workspace.
• Wrong environment selected, causing a write against production. Name environments clearly and double-check the selector in the top right.
• Unorganised requests. Use folders by resource and consistent naming such as "Create user".
• Stale collections that drift from the real API. Sync from an OpenAPI source or review regularly.

Where it fits in an architecture

Postman sits at the edge of the API lifecycle. Designers draft the contract in OpenAPI, developers explore and debug with Postman, testers turn collections into automated checks, and consumers read the published docs. It complements gateways and service meshes by giving humans a friendly view of the same endpoints those layers protect and route.

Key takeaways

• Use collections to organise and share requests, and workspaces to organise collaboration.
• Define environments with identical variable names so one collection runs anywhere.
• Keep secrets in current values or secret variables, never in initial values.
• Set authorisation at collection level so requests inherit it.
• Import curl or OpenAPI to start quickly, then move to the testing guide to automate.