Collections and folders in Postman - Deep Dive

Overview - Collections and folders

What is it?

Collections and folders in Postman are ways to organize your API requests. A collection is like a container that holds multiple requests, and folders help group related requests inside a collection. This structure helps testers keep their work neat and easy to find. It also allows running groups of requests together for testing workflows.

Why it matters

Without collections and folders, managing many API requests would be chaotic and error-prone. Testers would waste time searching for requests or accidentally run the wrong ones. Collections and folders make it simple to share tests with teammates, run automated tests in order, and keep projects organized, saving time and reducing mistakes.

Where it fits

Before learning collections and folders, you should understand what an API request is and how to create one in Postman. After mastering collections and folders, you can learn about running tests, using environments, and automating workflows with Postman.

Mental Model

Core Idea

Collections and folders organize API requests into manageable groups to simplify testing and collaboration.

Think of it like...

Think of collections as a filing cabinet and folders as folders inside that cabinet. Each folder holds related documents (requests), making it easy to find and work on specific topics without mixing everything up.

Collection
├── Folder 1
│   ├── Request A
│   └── Request B
├── Folder 2
│   ├── Request C
│   └── Request D
└── Request E (no folder)

Build-Up - 6 Steps

1

Foundation

Understanding API requests in Postman

Concept: Learn what an API request is and how to create one in Postman.

An API request is a message sent to a server to get or send data. In Postman, you create a request by choosing the method (GET, POST, etc.), entering the URL, and adding headers or body data if needed. You can then send the request and see the response.

Result

You can successfully send a single API request and view its response in Postman.

Knowing how to create and send requests is the base skill needed before organizing them into collections.

2

Foundation

Creating a collection in Postman

Concept: Introduce collections as containers to group API requests.

In Postman, a collection is a named group where you save related API requests. To create one, click 'New', select 'Collection', give it a name, and save. You can then add requests to this collection to keep them organized.

Result

You have a named collection ready to hold multiple API requests.

Collections help keep your API requests organized and easy to manage as your project grows.

3

Intermediate

Using folders inside collections

🤔Before reading on: do you think folders can exist outside collections or only inside? Commit to your answer.

Concept: Folders group related requests inside a collection for better organization.

Folders are like sub-groups inside a collection. You create a folder within a collection to group requests that belong together, such as all requests related to user management. This helps when you have many requests and want to find or run specific groups easily.

Result

You can organize requests into folders inside a collection, making navigation simpler.

Folders add a second layer of organization, which is crucial for large projects with many requests.

4

Intermediate

Running collections and folders as tests

🤔Before reading on: do you think you can run a single request, a folder, and a whole collection? Commit to your answer.

Concept: You can run all requests in a folder or collection in sequence to test workflows.

Postman lets you run a collection or a folder using the Collection Runner. This runs each request in order and shows results. It helps test how APIs work together, like logging in then fetching data. You can also add tests to requests to check responses automatically.

Result

You can execute multiple requests in order and see pass/fail results for tests.

Running grouped requests simulates real API workflows and automates testing, saving time and catching errors.

5

Advanced

Sharing and syncing collections with teams

🤔Before reading on: do you think collections are private by default or shared automatically? Commit to your answer.

Concept: Collections can be shared and synced with team members for collaboration.

Postman allows you to share collections with teammates by adding them to a workspace or exporting the collection file. Changes sync automatically in team workspaces, so everyone uses the latest tests. This avoids confusion and duplicated work.

Result

Teams can collaborate on API tests efficiently with shared collections.

Collaboration features in collections prevent version conflicts and improve team productivity.

6

Expert

Advanced folder usage with pre-request and test scripts

🤔Before reading on: do you think scripts can be added only to requests or also to folders? Commit to your answer.

Concept: Folders can have pre-request and test scripts that apply to all requests inside them.

In Postman, you can add scripts at the folder level that run before or after every request in that folder. For example, a pre-request script can set authentication tokens for all requests inside. This avoids repeating code and keeps tests consistent.

Result

Scripts run automatically for all requests in a folder, improving efficiency and reducing errors.

Folder-level scripts enable powerful, reusable setups and checks across multiple requests, a key to scalable test suites.

Under the Hood

Postman stores collections and folders as JSON files that define requests, scripts, and metadata. When you run a collection or folder, Postman reads this JSON, executes requests in order, and applies any scripts or tests attached. The UI reflects this structure, allowing easy navigation and editing. Syncing uses cloud storage to keep collections updated across devices and team members.

Why designed this way?

The JSON format makes collections portable and easy to share or version control. Grouping requests into collections and folders reflects how testers think about APIs in projects, from broad groups to specific features. Scripts at multiple levels reduce duplication and improve maintainability. Cloud syncing supports modern team collaboration needs.

Postman Collections JSON
┌─────────────────────────────┐
│ Collection Object           │
│ ├─ Info (name, description) │
│ ├─ Folders Array            │
│ │   ├─ Folder Object        │
│ │   │   ├─ Name             │
│ │   │   ├─ Requests Array   │
│ │   │   └─ Scripts          │
│ │   └─ ...                  │
│ ├─ Requests Array           │
│ └─ Scripts                  │
└─────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Can folders exist outside collections in Postman? Commit to yes or no.

Common Belief: Folders can be created independently, outside of collections.

Reality: Folders only exist inside collections; you cannot create folders outside collections.

Why it matters: Trying to organize requests with folders outside collections leads to confusion and inability to run grouped tests properly.

Quick: Does running a collection run requests in random order? Commit to yes or no.

Common Belief: Running a collection executes requests in any order or all at once.

Reality: Requests in a collection run sequentially in the order they appear.

Why it matters: Assuming random order can cause testers to miss dependencies between requests and get false test results.

Quick: Can scripts added to a folder override request-level scripts? Commit to yes or no.

Common Belief: Folder-level scripts replace or override scripts on individual requests.

Reality: Folder-level scripts run in addition to request-level scripts; they do not override them.

Why it matters: Misunderstanding script layering can cause unexpected test behavior or duplicated code execution.

Quick: Are collections automatically shared with your team by default? Commit to yes or no.

Common Belief: Collections are shared automatically with all team members once created.

Reality: Collections are private by default and must be explicitly shared or added to a team workspace.

Why it matters: Assuming automatic sharing can lead to confusion about test availability and version control.

Expert Zone

1

Folder-level pre-request and test scripts run before and after every request in that folder, allowing centralized setup and validation.

2

Collections can be exported and imported as JSON files, enabling version control and integration with CI/CD pipelines.

3

Postman’s collection runner supports data-driven testing by running requests multiple times with different input data from files.

When NOT to use

Avoid using deeply nested folders as it complicates navigation and maintenance; instead, split large collections into multiple smaller collections. For very simple projects, single collections without folders may suffice. When automation requires complex workflows, consider using Postman’s CLI tool Newman or dedicated API testing frameworks.

Production Patterns

In real projects, teams create collections per API service and use folders for features or user roles. Folder-level scripts manage authentication tokens or environment setup. Collections are integrated into CI pipelines using Newman to run tests automatically on code changes. Sharing collections in team workspaces ensures everyone tests with the latest API versions.

Connections

Version Control Systems (e.g., Git)

Collections as JSON files can be version controlled like code repositories.

Understanding collections as files helps grasp how API tests can be tracked, branched, and merged, just like software code.

Project Management Tools (e.g., Trello, Jira)

Collections and folders organize API tests similar to how tasks and subtasks organize work items.

Seeing collections as project boards helps appreciate the importance of clear structure for team collaboration and progress tracking.

Library Classification Systems

Organizing books into categories and shelves parallels grouping API requests into collections and folders.

Recognizing this connection highlights how good organization reduces search time and improves workflow efficiency.

Common Pitfalls

#1 Trying to create folders outside a collection.

Wrong approach:

Right-clicking in Postman’s main sidebar and selecting 'New Folder' without selecting a collection first.

Correct approach:

First create or select a collection, then inside it create a new folder.

Root cause:

Misunderstanding that folders are always nested inside collections, not standalone.

#2 Running a collection expecting requests to run in parallel.

Wrong approach:

Using the collection runner and assuming all requests execute at the same time.

Correct approach:

Understanding that Postman runs requests sequentially in the order listed.

Root cause:

Confusing Postman’s runner with parallel execution tools or misunderstanding request dependencies.

#3 Duplicating authentication code in every request instead of using folder scripts.

Wrong approach:

Adding the same pre-request script to each request individually.

Correct approach:

Adding a single pre-request script at the folder level to apply to all requests inside.

Root cause:

Not knowing that scripts can be applied at multiple levels, leading to redundant code and harder maintenance.

Key Takeaways

Collections and folders are essential for organizing API requests in Postman, making testing manageable and scalable.

Folders exist only inside collections and help group related requests for easier navigation and execution.

You can run all requests in a folder or collection sequentially to test API workflows and automate validation.

Scripts can be added at collection, folder, or request levels to reuse code and maintain consistency.

Sharing collections in team workspaces enables collaboration and keeps tests synchronized across team members.