Postman: API Testing and Development Guide

Postman is the most widely used API development and testing tool. It lets you send HTTP requests, inspect responses, organize APIs into collections, run automated tests, and generate documentation — all without writing a single line of infrastructure code.

Getting Started

Sending Your First Request

Postman provides a simple interface for crafting HTTP requests. Every request needs:

1. Method — GET, POST, PUT, PATCH, DELETE, or others
2. URL — the endpoint you are calling
3. Headers — authentication tokens, content types, etc.
4. Body — data sent with POST, PUT, and PATCH requests

GET https://api.example.com/users
Headers:
  Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
  Accept: application/json

Postman formats the response with syntax highlighting, showing status code, headers, and body in a clean interface. Large JSON responses are collapsible and searchable.

Request Parameters Tab

The Params tab lets you add query parameters or path variables without manually editing the URL. Key-value pairs are automatically URL-encoded, and you can bulk-edit or import parameters from a text editor. This is especially useful when testing paginated endpoints with multiple query parameters.

Collections

A collection is a group of related requests. Collections are the core organizing unit in Postman — they keep your API requests structured, shareable, and runnable as test suites.

Creating a Collection

New → Collection → Name it "Users API"
Add requests:
  GET    /users          → List all users
  GET    /users/:id      → Get a single user
  POST   /users          → Create a user
  PUT    /users/:id      → Update a user
  DELETE /users/:id      → Delete a user

Each request saves its URL, headers, body, and tests. You can nest requests in folders for logical grouping (e.g., “Authentication”, “Users”, “Orders”).

Collection-Level Authorization

Instead of setting authorization headers on every request, configure authentication at the collection level:

Collection → Authorization → Type: Bearer Token
Token: {{auth_token}}

All requests in the collection inherit this authorization setting. You can override it on individual requests when needed.

Sharing Collections

Collections can be exported as JSON files or shared via Postman’s cloud service:

# Export
Collection → Export → Collection v2.1

# Share
Collection → Share → Get public link

Team workspaces let multiple developers collaborate on the same collection in real time.

Variables

Variables make collections dynamic and environment-agnostic. Instead of hardcoding URLs or tokens, use variables:

Base URL:    {{base_url}}         → https://api.staging.example.com
Auth Token:  {{auth_token}}       → eyJhbGciOiJIUzI1NiIs...
User ID:     {{user_id}}          → 12345

Variable Scopes

Postman has a hierarchy of variable scopes, from lowest to highest priority:

1. Global — available everywhere
2. Collection — available within a specific collection
3. Environment — tied to a specific environment (dev, staging, prod)
4. Data — from data files used in collection runs
5. Local — temporary, from scripts

Environments

Environments let you switch between different configurations without editing requests:

Development Environment:
  base_url = http://localhost:3000
  api_key  = dev-key-123

Staging Environment:
  base_url = https://staging.example.com
  api_key  = staging-key-456

Production Environment:
  base_url = https://api.example.com
  api_key  = prod-key-789

Switch environments from the dropdown in the top-right corner. Every request instantly uses the new values.

Setting Variables from Scripts

// Pre-request script — set a variable before the request
pm.variables.set("timestamp", Date.now());

// Tests script — save a value from the response
pm.test("Save user ID", () => {
    const json = pm.response.json();
    pm.collectionVariables.set("user_id", json.id);
---);

Testing APIs with Postman

Writing Tests

Postman tests are JavaScript assertions that run after a response is received:

pm.test("Status code is 200", () => {
    pm.response.to.have.status(200);
---);

pm.test("Response has expected structure", () => {
    const json = pm.response.json();
    pm.expect(json).to.have.property("id");
    pm.expect(json).to.have.property("name");
    pm.expect(json.name).to.be.a("string");
---);

pm.test("Response time is acceptable", () => {
    pm.expect(pm.response.responseTime).to.be.below(500);
---);

Chaining Requests

Use variables to chain requests — save a value from one response and use it in the next:

// Tests script for POST /users
pm.test("Create user", () => {
    const json = pm.response.json();
    pm.collectionVariables.set("user_id", json.id);
    pm.collectionVariables.set("user_email", json.email);
---);

Then the next request uses {{user_id}} in its URL: GET /users/{{user_id}}

Schema Validation

Validate response structure against a predefined JSON schema:

const schema = {
    type: "object",
    required: ["id", "name", "email"],
    properties: {
        id: { type: "number" },
        name: { type: "string" },
        email: { type: "string", pattern: "^\\S+@\\S+$" }
    }
---;

pm.test("Response matches schema", () => {
    pm.response.to.have.jsonSchema(schema);
---);

Running Collections

The Collection Runner executes all requests in a collection in sequence:

# Run via UI
Collection → Run → Select environment → Run

# Run via CLI (Newman)
newman run UsersAPI.postman_collection.json \
  -e Staging.postman_environment.json \
  --reporters cli,htmlextra

Data-Driven Testing

Pass a CSV or JSON file with test data:

name,email,role
Alice,alice@example.com,admin
Bob,bob@example.com,user
Charlie,charlie@example.com,viewer

Postman runs the collection once for each row, using {{name}}, {{email}}, and {{role}} variables.

Pre-request Scripts

Pre-request scripts run before the request is sent. Use them to prepare data, generate timestamps, or compute signatures:

// Generate a dynamic timestamp
const now = new Date().toISOString();
pm.variables.set("current_time", now);

// Compute HMAC signature for authenticated requests
const crypto = require("crypto-js");
const secret = pm.environment.get("api_secret");
const signature = crypto.HmacSHA256(
    pm.request.url.toString(),
    secret
).toString();
pm.variables.set("signature", signature);

API Documentation

Postman can generate documentation from your collections:

1. Add descriptions to each request, parameter, and header
2. Click “View Documentation” to see the rendered docs
3. Publish documentation to a public or private web page

Published documentation includes:
- Request methods and URLs
- Headers, query parameters, and body schemas
- Example responses
- Code snippets in multiple languages (cURL, Python, JS, Go, etc.)

Example Generation

Postman auto-generates code snippets in multiple languages from any request. Click the “Code” button (</>) and select from cURL, Python Requests, JavaScript Fetch, Go, Java, Swift, and more. This is invaluable for sharing API call examples with your team or embedding them in documentation.

Workspaces and Collaboration

• Personal workspace — individual development
• Team workspace — shared collections, environments, and mocks
• Public workspace — API documentation, example collections

Team workspaces support comments, change tracking, and role-based permissions.

Mock Servers

Postman can create mock servers from your collections, allowing frontend teams to develop against a simulated API before the backend is ready:

Collection → Mock Server → Select environment → Create

The mock server returns realistic responses based on your saved examples. This decouples frontend and backend development and enables parallel workstreams.

Best Practices

1. Use environments for all configurations — never hardcode URLs or credentials
2. Write tests for every request — even simple status code checks catch regressions
3. Use pre-request scripts for dynamic data — timestamps, tokens, and signatures
4. Organize collections with folders — group related endpoints together
5. Version control your collections — export and commit them to your repository
6. Use Newman in CI/CD — automate API testing in your pipeline
7. Document as you build — add descriptions to requests immediately
8. Use collection variables for shared state — avoid global variables for scoped data

FAQ

What is the difference between Postman and Insomnia?

Both are API clients with similar features. Postman has a larger ecosystem (Newman, monitors, workspaces) and is more widely used in enterprise settings. Insomnia is lighter, has built-in GraphQL support, and is preferred by some developers for its cleaner interface.

How do I test authenticated endpoints in Postman?

Set up collection-level authorization with a token variable, then use a pre-request script or a separate “login” request to refresh the token. Store the token in a collection variable using pm.collectionVariables.set().

Can Postman handle file uploads?

Yes. Switch the request body type to “form-data” and use the “File” type selector. Postman automatically sets the correct Content-Type: multipart/form-data header with the proper boundary.

How do I debug failing Newman runs in CI?

Use the --reporters cli,htmlextra flags to generate an HTML report. Add --verbose for detailed request/response logging. Set environment variables via --env-var "key=value" for CI-specific configuration.

What is the Postman Interceptor?

The Interceptor is a browser extension that captures cookies and headers from your browser and forwards them to Postman. This is useful for debugging web applications that use session-based authentication.

Related: Learn REST API vs GraphQL and cURL for API testing.

Postman Collections and Environments

Postman collections organize API requests into reusable, shareable groups. Collection-level variables scope values across all requests, reducing repetition of base URLs, API keys, and IDs. Environment files (e.g., Development, Staging, Production) override collection variables with environment-specific values. Pre-request scripts run before each request, useful for generating timestamps, computing HMAC signatures, or refreshing OAuth tokens automatically. Test scripts in the Tests tab run after each response using Chai assertions: pm.test("Status is 200", () => pm.response.to.have.status(200)). The Collection Runner executes all requests in a collection sequentially, passing data between requests via pm.variables.set(). Newman, Postman’s CLI runner, integrates collections into CI/CD pipelines: newman run collection.json -e environment.json --reporters cli,junit. Postman Monitors run collections on a schedule from Postman’s cloud, alerting on failures.

API Documentation and Mock Servers

Postman generates human-readable API documentation from collections, including request/response examples, headers, and descriptions. Mock servers simulate API responses based on saved examples, enabling frontend and mobile development before the backend is complete. The API Builder feature supports designing APIs with OpenAPI/Swagger and generating collections from the spec. Postman Flows provides a visual, low-code interface for chaining API calls with conditional logic.