Postman Tutorial: Test an API Request Safely

Define the contract before clicking Send

Write down the HTTP method, path, required headers, expected status and smallest valid response shape. A green status alone does not prove the body is usable. In this tutorial the contract is a GET request to /users/42 that returns JSON with numeric id 42 and a non-empty name.

Use only an authorized target

Run requests against a local classroom service, a documented public sandbox or a system you are explicitly allowed to test. The downloadable collection defaults to 127.0.0.1 and does not contact a production service. Do not probe unrelated hosts, guess credentials or submit destructive requests.

Separate the base URL from the route

Store the environment-specific origin in baseUrl and the resource identifier in userId. The request becomes {{baseUrl}}/users/{{userId}}. This keeps the route readable and lets a learner change an authorized environment without editing every request.

Add only necessary headers

For this GET example, Accept: application/json states the response format the client can use. Content-Type describes a request body and is unnecessary when there is no body. Authentication is deliberately disabled in the sample. Never commit real tokens, passwords, cookies or private environment exports.

Assert the response contract

Add Post-response tests for status 200, a JSON Content-Type, numeric id matching userId and a non-empty string name. Each assertion answers a different question. If one fails, read its message instead of replacing a precise check with a broad status-only check.

Diagnose transport and contract failures

A refused localhost connection usually means the practice server is not running or the port differs. A 404 suggests the path or identifier is wrong. A 401 or 403 requires checking the authorized authentication setup; it is not a reason to bypass access controls. Invalid JSON or a changed field type is a contract failure even when the status is 200.

Save a reproducible collection

Give requests descriptive names, include a purpose and permission note, and keep example values non-sensitive. Export the collection without active secrets. A teammate should be able to import it, supply their own authorized environment and understand the expected response without reading chat history.

Extend the exercise deliberately

Add a permitted not-found case for a known absent user and assert its documented status and error shape. Then test a malformed response in a local mock. Do not turn the exercise into high-volume, load, security or destructive testing; those activities require separate scope, tooling and authorization.

Importable Postman Collection v2.1 (localhost by default)

{
  "info": {
    "_postman_id": "8e6747a2-e678-4baa-900b-68fe7c84a467",
    "name": "Local Users API Practice",
    "description": "Classroom collection for an API you own or are authorized to test. Default target is localhost.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "noauth"
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "http://127.0.0.1:3000",
      "type": "string"
    },
    {
      "key": "userId",
      "value": "42",
      "type": "string"
    }
  ],
  "item": [
    {
      "name": "Get one user",
      "request": {
        "auth": {
          "type": "noauth"
        },
        "method": "GET",
        "header": [
          {
            "key": "Accept",
            "value": "application/json",
            "type": "text"
          }
        ],
        "url": {
          "raw": "{{baseUrl}}/users/{{userId}}",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "users",
            "{{userId}}"
          ]
        },
        "description": "Run only against a local classroom API or another API you are authorized to test."
      },
      "event": [
        {
          "listen": "test",
          "script": {
            "type": "text/javascript",
            "exec": [
              "pm.test(\"status is 200\", function () {",
              "  pm.response.to.have.status(200);",
              "});",
              "pm.test(\"response is JSON\", function () {",
              "  pm.expect(pm.response.headers.get(\"Content-Type\")).to.include(\"application/json\");",
              "});",
              "pm.test(\"user shape matches the contract\", function () {",
              "  const body = pm.response.json();",
              "  pm.expect(body).to.have.property(\"id\", Number(pm.variables.get(\"userId\")));",
              "  pm.expect(body).to.have.property(\"name\").that.is.a(\"string\").and.not.empty;",
              "});"
            ]
          }
        }
      ]
    }
  ]
}

Expected result

With an authorized local API returning {"id":42,"name":"Asha"} as JSON, all three tests pass. Connection, status, header or response-shape differences fail with a specific assertion.

Further reading

• Postman Docs: write scripts to test API response data
• Postman Docs: group requests in collections