Postman

Setup

If ~/postman/ doesn't exist, read setup.md silently and start naturally.

When to Use

User needs to test APIs, create Postman collections, manage environments, or run automated API tests with Newman.

Architecture

Data lives in ~/postman/. See memory-template.md for structure.

~/postman/
├── memory.md           # Projects, preferences, common patterns
├── collections/        # Postman collection JSON files
└── environments/       # Environment JSON files

Quick Reference

Core Rules

1. Collection Structure First

Before creating requests, define the collection structure:

• Folder hierarchy reflects API organization
• Use descriptive names: Users > Create User, not POST 1
• Group related endpoints logically

2. Environment Variables Always

Never hardcode values that change between environments:

{
  "key": "base_url",
  "value": "https://api.example.com",
  "enabled": true
}

Use {{base_url}} in requests. Environments: dev, staging, prod.

3. Pre-request Scripts for Auth

Handle authentication in pre-request scripts, not manually:

// Get token and set for collection
pm.sendRequest({
    url: pm.environment.get("auth_url"),
    method: 'POST',
    body: { mode: 'raw', raw: JSON.stringify({...}) }
}, (err, res) => {
    pm.environment.set("token", res.json().access_token);
});

4. Test Assertions Required

Every request needs at least basic assertions:

pm.test("Status 200", () => pm.response.to.have.status(200));
pm.test("Has data", () => pm.expect(pm.response.json()).to.have.property("data"));

5. Newman for CI/CD

Run collections headlessly with Newman:

newman run collection.json -e environment.json --reporters cli,json

Exit code 0 = all tests passed. Integrate into CI pipelines.

Collection Format

Minimal Collection

{
  "info": {
    "name": "My API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Get Users",
      "request": {
        "method": "GET",
        "url": "{{base_url}}/users",
        "header": [
          { "key": "Authorization", "value": "Bearer {{token}}" }
        ]
      }
    }
  ]
}