Mastering API Testing with Postman: A Comprehensive Guide for Developers

Postman is a desktop and web application for sending HTTP requests to an API, checking the responses, and turning those checks into automated tests. It is one of the quickest ways to see what an API really returns before you write code against it. This guide covers the workflow developers use most: requests, collections, variables, test scripts, and running the same tests from the command line and CI.

1. What Postman is good for

• Exploring an API: send a request, read the status, headers and body, and adjust until it works.
• Regression tests: scripts that check every response, run with one click or on every commit.
• Sharing: a collection documents an API with working examples your team can run.
• Debugging: the Postman Console shows exactly what was sent and received, including redirects.

Postman supports REST, GraphQL, gRPC, WebSocket and SOAP requests. It runs on Windows, macOS and Linux, and in a browser. It needs a free account; features such as team workspaces and scheduled monitors depend on your plan, so check Postman's current plan limits before you rely on them. Open-source alternatives with a similar workflow include Bruno, Insomnia and Hoppscotch.

2. Your first request

To send data, open the Body tab. Choose raw and JSON for a JSON payload (Postman sets Content-Type: application/json), form-data for file uploads and multipart forms, or x-www-form-urlencoded for classic HTML form posts.

{
  "name": "Asha Rao",
  "email": "[email protected]"
}

3. Authentication

The Authorization tab can be set on a request, a folder or a whole collection; child requests inherit it.

• API key: sent as a header (for example X-API-Key) or a query parameter, whichever the API expects. Prefer a header, because URLs end up in logs.
• Bearer token: Authorization: Bearer YOUR_TOKEN, used by most token and JWT-based APIs.
• Basic auth: Postman Base64-encodes username:password. Base64 is encoding, not encryption, so use it only over HTTPS.
• OAuth 2.0: Postman can run the whole flow for you. Fill in the provider's authorisation and token URLs, client ID and scope, click Get New Access Token, and Postman stores and attaches the token.

For how these methods compare, see navigating the evolution of API authentication.

4. Collections and variables

A collection groups related requests into folders, such as Users, Orders and Payments, and can hold shared authorisation, scripts and variables. Save every request you want to keep into one. Collections can be exported as JSON (format v2.1) and imported elsewhere.

Variables stop you hard-coding values. Write {{base_url}}/users and define base_url once. Variables exist at several levels, and the narrowest one wins:

Create one environment per stage, all with the same variable names, and switch between them from the environment menu. Postman also has built-in dynamic variables such as {{$guid}}, {{$timestamp}} and {{$randomEmail}} for test data.

5. Writing tests

Tests are JavaScript that runs after the response arrives. In current Postman versions they live on the Scripts tab, under Post-response; older guides call this the Tests tab.

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

pm.test("Responds in under 800 ms", () => {
  pm.expect(pm.response.responseTime).to.be.below(800);
});

pm.test("Returns the user we asked for", () => {
  const body = pm.response.json();
  pm.expect(body).to.have.property("id");
  pm.expect(body.email).to.eql("[email protected]");
});

Pre-request scripts run before the request is sent, for example to set a timestamp or build a signature:

pm.environment.set("request_time", new Date().toISOString());

Chaining requests. Save a value from one response and use it in the next request:

// Post-response script on "Create user"
const user = pm.response.json();
pm.collectionVariables.set("user_id", user.id);

The next request can then call {{base_url}}/users/{{user_id}}. During a collection run, pm.execution.setNextRequest("Request name") jumps to a named request and pm.execution.setNextRequest(null) stops the run. The older postman.setNextRequest() form still appears in many guides.

To check the whole shape of a response, pm.response.to.have.jsonSchema(schema) validates it against a JSON Schema you define in the script.

6. Running collections and debugging

The Collection Runner (the Run button on a collection) executes every request in order with the chosen environment, a number of iterations and an optional delay. You can feed it a CSV or JSON data file to run the same requests with many inputs.

When something fails, open the Console from the bottom bar. It shows every request exactly as sent, including resolved variables, headers and redirects, plus anything you print with console.log().

Read the status code before the body:

• 400 or 422: the request is malformed or fails validation; check the body and Content-Type.
• 401: missing or invalid credentials. 403: valid credentials without permission.
• 404: wrong URL or ID, often an unresolved {{variable}} shown in red.
• 429: rate limited; slow down or respect Retry-After.
• 500 to 504: a server-side error; check the API's own logs.

A browser CORS error does not happen in Postman, because CORS is enforced by browsers only. If a call works in Postman but fails in your web page, the API's Access-Control-Allow-Origin headers are the likely cause.

7. Automating in CI with Newman or the Postman CLI

Newman is the open-source command-line runner for exported collections. Install it with npm on a current Node.js LTS release:

npm install -g newman
newman run api.postman_collection.json \
  -e staging.postman_environment.json \
  --reporters cli,junit --reporter-junit-export results.xml

The JUnit report can be read by most CI systems. An HTML report needs an extra reporter package, such as newman-reporter-htmlextra. The Postman CLI is Postman's own runner; it runs collections straight from your Postman workspace with postman collection run COLLECTION_ID after postman login with an API key.

A minimal GitHub Actions job:

name: API tests
on: [push]
jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: lts/*
      - run: npm install -g newman
      - run: newman run tests/api.postman_collection.json -e tests/staging.postman_environment.json --env-var "api_key=${{ secrets.API_KEY }}"

Pass secrets from the CI system's secret store with --env-var, as above, rather than storing them in the environment file. Postman monitors can also run a collection on a schedule from Postman's cloud, but they cannot reach localhost or private networks.

8. Testing APIs hosted on Domain India

• App Platform. Node.js apps are detected automatically; other languages deploy with a Dockerfile. Point {{base_url}} at the app's domain and run the same collection after each deploy. See getting started with the App Platform.
• PHP APIs on cPanel hosting. Our cPanel servers run nginx in front of Apache, and nginx can cache successful responses for up to two hours. If a GET keeps returning an old response after you change your code, add a throwaway query parameter such as ?t={{$timestamp}} while testing.
• The cPanel UAPI. You can call your own account's API from Postman on port 2083. Create a token in cPanel under Security › Manage API Tokens, then send GET https://your-panel-host:2083/execute/Email/list_pops with the header Authorization: cpanel yourusername:YOURTOKEN. Use the panel address shown in your hosting service's Access tab in the client area. WHM's API is not available on shared hosting accounts.

The plan card shows a live Domain India list price, excluding 18% GST.

Ready to test your own API? Deploy it on the App Platform or on cPanel hosting, then point a Postman environment at it. For API design background, read RESTful API design, patterns and debugging.