Introduction to Postman Collections

In this tutorial, you will learn about Introduction to Postman Collections. We cover key concepts, practical examples, and best practices to help you master this topic.

Postman collections are organized groups of API requests that can be saved, shared, and automated. They serve as executable documentation, test suites, and development aids. Collections support variables, scripts, and environment integration.

What You'll Learn

• What Postman collections are and why they matter
• Collection structure: requests, folders, scripts
• Sharing and collaboration features
• Newman integration for automation

Why It Matters

Collections transform ad-hoc API requests into reusable, shareable assets. Teams use collections for onboarding, testing, and documentation. Collections with Newman power automated API testing in CI/CD.

Real-World Use

Stripe publishes Postman collections for their payment API. GitHub provides collections for their REST and Graphql APIs. Most major API providers offer Postman collections for developer onboarding.

flowchart LR
    Collection[Postman Collection] --> Requests[API Requests]
    Collection --> Scripts[Pre-request & Test Scripts]
    Collection --> Variables[Collection Variables]
    Collection --> Folders[Folder Organization]
    Collection --> Environments[Environment Configs]
    Collection --> Newman[Newman CI/CD Runner]

Teacher Mindset

Think of a collection as an API cookbook. Each request is a recipe with ingredients (headers, body), instructions (pre-request scripts), and quality checks (test scripts). Share collections to spread API knowledge.

Code Examples

// Example 1: Collection-level test script
// Runs after every request in the collection
pm.test('Response time is acceptable', () => {
    pm.expect(pm.response.responseTime).to.be.below(5000);
});

pm.test('No server errors', () => {
    pm.expect(pm.response.code).to.be.oneOf([200, 201, 204, 400, 401, 403, 404]);
});

// Example 2: Collection-level pre-request script
// Sets common headers for all requests
pm.request.headers.add({
    key: 'X-Client-Id',
    value: pm.variables.get('client_id')
});

pm.request.headers.add({
    key: 'X-Request-Id',
    value: require('uuid').v4()
});

// Example 3: Exporting collection as JSON
// Postman collection structure (simplified)
{
  "info": {
    "name": "E-Commerce API",
    "description": "Collection for testing the e-commerce API"
  },
  "item": [
    {
      "name": "Users",
      "item": [
        {
          "name": "Get Users",
          "request": { "method": "GET", "url": "{{base_url}}/api/users" }
        }
      ]
    }
  ],
  "variable": [
    { "key": "base_url", "value": "http://localhost:3000" }
  ]
}

Common Mistakes

• Not using variables, hardcoding URLs and tokens
• Ignoring collection-level scripts for shared logic
• Creating collections without folder organization
• Forgetting to add descriptions to requests
• Not testing collections with Newman before sharing

Practice

1. Create a new collection named "My API Tests".
2. Add a folder for Users and a folder for Products.
3. Add one GET request to each folder.
4. Set a collection-level variable for base_url.
5. Challenge: Export the collection as JSON and inspect the structure.

FAQ

Mini Project

Create a Postman collection for a sample API with two folders (Users, Products), one request in each folder, collection-level variables for base URL, and a collection-level test script that checks response time under 3 seconds.

What's Next

Next, you will learn about setting up Postman for efficient API development and testing.