Creating collections in Postman - Mechanics & Internals

Overview - Creating collections

What is it?

Creating collections in Postman means grouping related API requests together in one organized place. Each collection can hold multiple requests, scripts, and tests that help you manage and run your API tests easily. Collections make it simple to share and reuse your API tests with others. They act like folders that keep your work neat and accessible.

Why it matters

Without collections, managing many API requests would be chaotic and error-prone. You would have to remember each request's details separately, making testing slow and confusing. Collections solve this by bundling requests logically, improving teamwork, saving time, and reducing mistakes. They help teams deliver reliable software faster by organizing tests clearly.

Where it fits

Before learning collections, you should understand basic API requests and how to send them in Postman. After mastering collections, you can explore running automated tests, using environments, and integrating collections into continuous integration pipelines for advanced testing workflows.

Mental Model

Core Idea

A Postman collection is like a digital folder that groups related API requests and tests to organize and run them efficiently.

Think of it like...

Imagine a recipe book where each chapter groups recipes by type, like desserts or soups. Collections are like those chapters, grouping similar API requests so you can find and use them easily.

┌─────────────────────────────┐
│        Collection           │
│ ┌───────────────┐           │
│ │ Request 1     │           │
│ ├───────────────┤           │
│ │ Request 2     │           │
│ ├───────────────┤           │
│ │ Request 3     │           │
│ └───────────────┘           │
│  Scripts & Tests             │
└─────────────────────────────┘

Build-Up - 6 Steps

1

Foundation

Understanding API Requests in Postman

Concept: Learn what an API request is and how to send one using Postman.

An API request is a message sent to a server asking for data or action. In Postman, you create a request by choosing the method (GET, POST, etc.), entering the URL, and optionally adding headers or body data. Then you click 'Send' to see the response.

Result

You see the server's response data, status code, and headers in Postman.

Knowing how to send a single API request is the base skill needed before grouping requests into collections.

2

Foundation

What is a Collection in Postman

Concept: Introduce the idea of grouping API requests into collections for better organization.

A collection is a container in Postman where you save multiple API requests together. You can create a new collection, name it, and add requests to it. This helps keep related requests in one place instead of scattered.

Result

You have a named collection visible in Postman with saved requests inside.

Understanding collections as folders helps you organize your work and makes testing easier.

3

Intermediate

Adding Requests to Collections

🤔Before reading on: Do you think you can add a request to multiple collections at once? Commit to your answer.

Concept: Learn how to save existing or new requests into a collection and understand collection structure.

When you create or open a request, you can click 'Save' and choose to save it inside a collection. Each request belongs to one collection. You can also create folders inside collections to group requests further.

Result

Requests are neatly saved inside collections and folders, visible in the sidebar.

Knowing that requests belong to one collection at a time helps avoid confusion and keeps organization clear.

4

Intermediate

Using Scripts and Tests in Collections

🤔Before reading on: Do you think scripts in collections run automatically for every request? Commit to your answer.

Concept: Collections can hold scripts that run before or after requests to automate checks and setup.

You can add pre-request scripts to run code before sending a request, and test scripts to check responses after. These scripts help automate validation and setup tasks. Scripts can be added at the collection level to apply to all requests inside.

Result

Scripts run automatically when requests in the collection execute, helping catch errors or prepare data.

Understanding scripts at the collection level saves time by avoiding repetition and ensures consistent testing.

5

Advanced

Exporting and Sharing Collections

🤔Before reading on: Can you share a collection without sharing your environment variables? Commit to your answer.

Concept: Learn how to export collections to share with teammates or import collections others shared.

Postman lets you export collections as JSON files. You can send these files to others who can import them into their Postman app. Collections do not include environment variables unless exported separately, keeping sensitive data safe.

Result

You can collaborate by sharing collections without exposing private data.

Knowing how to share collections securely enables teamwork and reuse without risking sensitive information.

6

Expert

Integrating Collections into Automated Workflows

🤔Before reading on: Do you think collections can run outside Postman app automatically? Commit to your answer.

Concept: Explore how collections can be run automatically using command-line tools and CI/CD pipelines.

Postman collections can be run using Newman, a command-line tool. This allows running tests in automated environments like build servers. You can schedule runs, integrate with version control, and generate reports, making testing part of software delivery.

Result

Collections run automatically in pipelines, catching issues early and improving software quality.

Understanding automation with collections transforms manual testing into continuous quality checks in real projects.

Under the Hood

Internally, a Postman collection is a JSON file that stores all request details, scripts, and metadata. When you run a collection, Postman or Newman reads this JSON, executes each request in order, runs scripts, and collects results. This structure allows easy sharing and automation.

Why designed this way?

The JSON format was chosen for its simplicity, readability, and compatibility with many tools. It allows collections to be portable and editable outside Postman, supporting collaboration and automation. Grouping requests with scripts in one file reduces complexity and improves maintainability.

┌───────────────┐
│ Collection.json│
├───────────────┤
│ Requests      │
│ - URL        │
│ - Method     │
│ - Headers    │
│ Scripts      │
│ - Pre-request│
│ - Tests      │
│ Metadata     │
└───────────────┘
       ↓
┌───────────────┐
│ Postman/Newman│
│ Executes each │
│ request & runs│
│ scripts       │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Can a single request belong to multiple collections at the same time? Commit to yes or no.

Common Belief: A request can be saved in many collections simultaneously for reuse.

Reality: Each request belongs to only one collection at a time. To reuse a request, you must duplicate it in other collections.

Why it matters: Assuming requests can be shared across collections leads to confusion and accidental edits affecting multiple places.

Quick: Do collection scripts run automatically for every request inside the collection? Commit to yes or no.

Common Belief: Scripts added to a collection run for every request inside it without extra setup.

Reality: Collection-level scripts run only if they are pre-request or test scripts defined at the collection level, not all scripts run automatically for every request.

Why it matters: Misunderstanding script scope causes tests to fail silently or run unexpectedly, wasting debugging time.

Quick: Does exporting a collection include your environment variables? Commit to yes or no.

Common Belief: Exporting a collection also exports all environment variables linked to it.

Reality: Collections and environments are exported separately. Environment variables are not included in collection exports to protect sensitive data.

Why it matters: Sharing collections without environments can cause tests to fail if variables are missing, leading to confusion.

Quick: Can you run Postman collections automatically outside the Postman app? Commit to yes or no.

Common Belief: Collections can only be run manually inside the Postman app.

Reality: Using Newman, collections can be run automatically in command-line environments and CI/CD pipelines.

Why it matters: Not knowing this limits testing to manual steps, missing out on automation benefits.

Expert Zone

1

Collection scripts can access and modify variables at different scopes (global, environment, collection), enabling complex test setups.

2

Folder-level scripts inside collections allow grouping requests with shared setup or tests, adding modularity beyond just collections.

3

Newman supports detailed reporting and integration with many CI tools, but requires careful configuration to handle environment secrets securely.

When NOT to use

Collections are not ideal for testing non-HTTP protocols or very large-scale load testing; specialized tools like JMeter or Gatling are better suited. For simple one-off requests, creating a collection may be unnecessary overhead.

Production Patterns

Teams use collections to version control API tests alongside code, run them automatically on each code commit, and share them via Postman cloud workspaces. Collections often include environment-specific variables to test multiple deployment stages.

Connections

Version Control Systems (e.g., Git)

Collections as JSON files can be stored and versioned in Git repositories.

Understanding collections as code-like files helps integrate API tests into software development workflows, enabling collaboration and history tracking.

Continuous Integration/Continuous Deployment (CI/CD)

Collections run automatically in CI/CD pipelines to validate APIs during software delivery.

Knowing how collections fit into CI/CD shows how testing becomes part of automated quality assurance, catching bugs early.

Library Cataloging Systems

Both organize many items into logical groups for easy retrieval and reuse.

Seeing collections like library catalogs helps appreciate the importance of organization in managing complex information.

Common Pitfalls

#1 Saving requests outside collections leads to disorganized tests.

Wrong approach:

Creating many requests in Postman but never saving them to any collection.

Correct approach:

Always save requests inside named collections to keep them organized and reusable.

Root cause:

Not understanding the purpose of collections as organizational tools.

#2 Sharing collections without environment variables causes test failures.

Wrong approach:

Exporting and sharing only the collection JSON file expecting tests to run correctly elsewhere.

Correct approach:

Export and share environment files separately or document required variables for others.

Root cause:

Assuming collections include all necessary data for tests to run.

#3 Adding the same request to multiple collections by copying causes maintenance issues.

Wrong approach:

Duplicating requests manually across collections without central management.

Correct approach:

Use collection folders or shared environments to reduce duplication and ease updates.

Root cause:

Not knowing that requests belong to one collection and duplication increases errors.

Key Takeaways

Postman collections group related API requests and tests into organized containers for easy management.

Each request belongs to one collection, and collections can include scripts to automate testing steps.

Collections are saved as JSON files, enabling sharing, version control, and automation outside the Postman app.

Understanding collections unlocks efficient API testing workflows and collaboration in teams.

Automating collections with tools like Newman integrates API testing into continuous software delivery.