Why this matters
Postman Collections turn scattered API requests into a single, organized, executable source of truth. As an API Engineer, you will:
- Ship a shareable collection so frontend and partner teams can explore and call your API in minutes.
- Automate smoke tests for critical endpoints before every deploy.
- Publish up-to-date examples and environment-aware variables without rewriting docs.
- Demonstrate API changes with versioned collections and clear diffs.
Concept explained simply
A Postman Collection is a folder of API requests with shared settings (auth, variables, scripts, examples). Think of it as a living manual that can also run itself.
Mental model
- Collection = book
- Folder = chapter
- Request = page with details (URL, method, body)
- Variables = placeholders you fill per environment (dev, staging, prod)
- Pre-request script = set the stage before a request
- Test script = check outcomes after a request
- Examples = screenshots of correct outputs (but for JSON)
Core components you will use
- Structure: Collections, folders, requests
- Variables: collection, environment, local, data file
- Auth: inherit from parent vs per-request overrides
- Scripts: pre-request and tests (pm.* API)
- Examples: documented example responses
- Runners: run whole folders with data
- Export/import: share as JSON
Worked examples
1) CRUD users with variables and auth inheritance
- Create a collection "User Service". Set a collection variable: base_url = https://api.example.test
- Set collection-level Auth: Type = Bearer Token, Token = {{api_token}}
- Create environment "Staging" with variables: api_token, base_url = https://staging.example.test
- Add requests:
- GET {{base_url}}/users
- POST {{base_url}}/users (JSON body: {"email":"test@example.com"})
- GET {{base_url}}/users/{{user_id}}
- DELETE {{base_url}}/users/{{user_id}}
- Set a test script on GET /users to assert status 200 and JSON array.
{"script":"pm.test('status 200', function(){ pm.response.to.have.status(200); }); pm.test('is array', function(){ pm.expect(pm.response.json()).to.be.an('array'); });"}
Result: Requests inherit auth; environment swaps URLs and tokens without editing requests.
2) Pre-request script to refresh token
- Add a hidden request folder "Auth" with a request POST {{base_auth_url}}/oauth/token.
- On the collection, add a pre-request script that runs when token is missing or expired (pseudo):
{"script":"if(!pm.collectionVariables.get('access_token') || Date.now() > pm.collectionVariables.get('token_exp')){ pm.sendRequest({url: pm.environment.get('base_auth_url') + '/oauth/token', method: 'POST', header:{'Content-Type':'application/json'}, body:{mode:'raw', raw: JSON.stringify({client_id: pm.environment.get('client_id'), client_secret: pm.environment.get('client_secret'), grant_type:'client_credentials'})}}, function(err, res){ if(!err){ const data = res.json(); pm.collectionVariables.set('access_token', data.access_token); pm.collectionVariables.set('token_exp', Date.now() + (data.expires_in-30)*1000); pm.request.headers.add({key:'Authorization',value:'Bearer '+data.access_token}); }}); }"} - Set collection-level Auth to "Inherit auth from parent" and rely on the pre-request script to attach Authorization header.
Result: Running any request automatically fetches and reuses a valid token.
3) Examples to power documentation
- Open GET {{base_url}}/users/{{user_id}}
- Send a real request, confirm 200.
- Click "Save Response" as example, give it a name "200 OK".
- Add another example with 404 payload explaining not found.
Result: Consumers see clear success and error responses in generated docs and can try them instantly.
How to build a clean collection
- One purpose per folder (e.g., Auth, Users, Orders).
- Use naming conventions: [GET] /users, [POST] /users, [GET] /users/:id.
- Put shared auth and headers at collection level; override only when needed.
- Document variables in a request description (e.g., {{base_url}} means environment base URL).
- Keep test scripts small and focused; move reusable snippets into collection-level scripts or use variables.
Environments and variables
Where variables live:
- Environment: change per dev/stage/prod (base_url, tokens)
- Collection: common to all environments (feature flags, default limits)
- Local (temporary): single request run
- Data file (runner): drive multiple inputs (CSV/JSON)
Reference: {{var_name}}. In scripts, pm.environment.get('name'), pm.collectionVariables.get('name').
Generate docs and share safely
- Write request descriptions with short purpose, required params, and response notes.
- Add examples for success and common errors.
- Export the collection JSON to share; exclude secrets by keeping them in environments.
- Provide a "Getting started" folder with a simple health check and auth step.
Testing and automation
- Pre-request: set headers, timestamps, signatures.
- Tests: validate status, schema shape, response time.
- Runner: execute folders; add a data file to iterate.
- Monitors/CI with Newman: run the collection on every push to catch regressions.
Useful test snippets
pm.test('status 2xx', () => pm.expect(pm.response.code).to.be.within(200,299));
pm.test('JSON body', () => pm.response.to.be.withBody && pm.response.to.be.json);
const body = pm.response.json();
pm.test('has id', () => pm.expect(body).to.have.property('id'));
pm.test('response time < 800ms', () => pm.expect(pm.response.responseTime).below(800));Versioning and collaboration
- Duplicate and suffix versions (v1, v2) during breaking changes.
- Use separate environments per branch (feature vs main).
- Add change notes in the collection description; keep request-level changelogs brief.
Exercises you can do now
These mirror the exercises below and help you build muscle memory.
- ex1: Build a mini CRUD collection with variables and tests.
- ex2: Add examples and a smoke test runner.
- Checklist:
- Collection has folders and clear names
- Auth is inherited
- Variables are documented
- At least 3 test assertions exist
- Two example responses saved
Progress tip
The quick test is available to everyone. If you log in, your progress and test history will be saved.
Common mistakes and how to self-check
- Hardcoding URLs or tokens: replace with {{base_url}} and {{api_token}}; verify by switching environments.
- Duplicated headers per request: move them to collection-level.
- Overlong scripts: extract values into variables; keep scripts concise.
- No examples: add at least a 200 and an error example per key endpoint.
- Unclear naming: use method tags [GET]/[POST] at the start.
Self-check
- Switch environment from staging to prod (or mock) without editing a request.
- Run all tests; zero failures.
- Someone new can authenticate and make a call in under 5 minutes using your collection.
Practical projects
- Starter collection for your service: health, auth, two entities with CRUD, tests, and examples.
- Error catalogue: create a folder that demonstrates common error responses with examples.
- Performance smoke: add response time assertions on top 5 endpoints.
- Data-driven run: import a CSV to create 10 resources and verify IDs are unique.
Who this is for
- API Engineers shaping public/internal APIs.
- Backend devs handing off to frontend/partners.
- QA engineers automating contract and smoke tests.
Prerequisites
- Basic HTTP knowledge (methods, headers, status codes).
- JSON formatting.
- Understanding of your service’s auth (API key, OAuth2, JWT).
Learning path
- Structure collections and environments.
- Add variables and inherited auth.
- Write minimal tests and pre-request scripts.
- Save examples and descriptions for docs.
- Automate runs locally and in CI using exported collection.
Next steps
- Refine tests to cover edge cases and non-200 responses.
- Expand examples with pagination and filtering.
- Export the collection and share with your team for feedback.
Mini challenge
Create a "Getting Started" folder with one-click auth, a health check, and a sample create-and-fetch flow. Add two examples (success + validation error) and three tests.