Folder hierarchy in Postman - Deep Dive

Overview - Folder hierarchy

What is it?

Folder hierarchy in Postman is a way to organize your API requests into nested folders. It helps you group related requests together so you can find and run them easily. Each folder can contain requests or other folders, creating a tree-like structure. This makes managing large collections simpler and clearer.

Why it matters

Without folder hierarchy, your API requests would be a long, unorganized list, making it hard to find or run specific tests quickly. This slows down your work and increases mistakes. Folder hierarchy solves this by grouping requests logically, improving efficiency and reducing errors in testing workflows.

Where it fits

Before learning folder hierarchy, you should understand how to create and send basic API requests in Postman. After mastering folder hierarchy, you can explore advanced features like environment variables, test scripts, and automated test runs using collections.

Mental Model

Core Idea

Folder hierarchy is like a filing cabinet that organizes your API requests into nested folders for easy access and management.

Think of it like...

Imagine your API requests are papers on your desk. Without folders, they are messy and hard to find. Using folder hierarchy is like putting those papers into labeled folders and subfolders inside a filing cabinet, so you can quickly find what you need.

Collection
├── Folder A
│   ├── Request 1
│   ├── Request 2
│   └── Subfolder A1
│       └── Request 3
└── Folder B
    └── Request 4

Build-Up - 6 Steps

1

Foundation

Understanding Postman Collections

Concept: Learn what a Postman collection is and how it groups API requests.

A Postman collection is a container for API requests. It lets you save and organize requests you want to test. Think of it as a folder that holds all your API calls for a project.

Result

You can create a collection and add requests to it, keeping your API tests in one place.

Knowing collections is essential because folder hierarchy exists inside collections to organize requests better.

2

Foundation

Creating Basic Folders in Collections

Concept: Learn how to create folders inside a collection to group requests.

Inside a collection, you can create folders by clicking 'Add Folder'. Name the folder to represent a group of related API requests, like 'User APIs'. Then, add requests into this folder.

Result

Your collection now has a folder that groups related requests, making it easier to find them.

Folders help break down large collections into manageable parts, improving clarity.

3

Intermediate

Using Nested Folders for Deeper Organization

🤔Before reading on: do you think folders can contain other folders or only requests? Commit to your answer.

Concept: Folders can contain other folders, creating a nested hierarchy.

You can create subfolders inside folders to organize requests even more specifically. For example, inside 'User APIs', create 'Authentication' and 'Profile' subfolders. This nesting helps manage complex projects.

Result

Your collection has a tree structure with folders inside folders, grouping requests logically.

Nested folders allow scalable organization, preventing clutter as your API tests grow.

4

Intermediate

Managing Folder Properties and Settings

🤔Before reading on: do you think folders can have settings like authorization or variables? Commit to your answer.

Concept: Folders can have their own settings that apply to all requests inside them.

You can set authorization, pre-request scripts, or variables at the folder level. These settings apply to every request inside that folder, saving time and ensuring consistency.

Result

Requests inside the folder inherit the folder's settings unless overridden individually.

Folder-level settings reduce repetition and help maintain consistent test environments.

5

Advanced

Running Folder Hierarchies in Automated Tests

🤔Before reading on: do you think you can run tests on a whole folder or only individual requests? Commit to your answer.

Concept: You can run all requests inside a folder or nested folders as a group in automated test runs.

Postman lets you run a folder or subfolder in the Collection Runner. This executes all requests inside, respecting folder-level settings and scripts. It helps automate testing of grouped APIs.

Result

You get a test run report for all requests in the folder, making batch testing efficient.

Running folders as units streamlines testing workflows and supports continuous integration.

6

Expert

Optimizing Folder Hierarchy for Collaboration

🤔Before reading on: do you think folder hierarchy affects team collaboration? Commit to your answer.

Concept: A well-designed folder hierarchy improves team collaboration and reduces conflicts.

When teams share collections, a clear folder structure helps everyone find and update requests without confusion. Naming conventions and consistent folder use prevent duplicated work and merge conflicts.

Result

Teams work faster and with fewer errors when folder hierarchy is thoughtfully planned.

Understanding folder hierarchy's impact on collaboration helps build maintainable, scalable test suites.

Under the Hood

Postman stores collections as JSON files where folders are objects containing arrays of requests or other folders. When you run a folder, Postman traverses this JSON tree, applying folder-level settings to each request dynamically before sending. This hierarchical inheritance ensures settings cascade properly.

Why designed this way?

The folder hierarchy mimics familiar file systems, making it intuitive. Using JSON allows easy sharing and version control. Inheritance of settings reduces duplication and errors, supporting large, complex API projects.

Collection (JSON object)
├── Folder (object)
│   ├── Settings (auth, scripts)
│   ├── Requests (array)
│   └── Subfolders (array of Folder objects)
└── Requests (array)

Myth Busters - 4 Common Misconceptions

Quick: Do folder settings override request settings or vice versa? Commit to your answer.

Common Belief: Folder settings always override individual request settings.

Reality: Individual request settings override folder settings if both exist.

Why it matters: Assuming folder settings always override can cause unexpected test behavior and debugging confusion.

Quick: Can you run only part of a folder's requests by selecting some requests? Commit to your answer.

Common Belief: You can select and run only some requests inside a folder directly.

Reality: Postman runs all requests in a folder or subfolder; partial runs require separate folders or manual selection.

Why it matters: Misunderstanding this leads to inefficient test runs and difficulty isolating tests.

Quick: Does nesting folders infinitely improve organization? Commit to your answer.

Common Belief: More nested folders always make organization better.

Reality: Too deep nesting can make navigation confusing and slow.

Why it matters: Over-nesting reduces usability and increases maintenance overhead.

Quick: Are folders just visual groups with no effect on test execution? Commit to your answer.

Common Belief: Folders only organize visually and do not affect test runs or settings.

Reality: Folders affect test execution by applying settings and controlling run scopes.

Why it matters: Ignoring folder effects can cause unexpected test results and wasted debugging time.

Expert Zone

1

Folder-level pre-request and test scripts run before and after every request inside, enabling shared setup and teardown logic.

2

Environment and global variables can be overridden at folder level, allowing flexible test configurations per folder.

3

When exporting collections, folder hierarchy is preserved in JSON, but some tools may flatten it, causing integration issues.

When NOT to use

Avoid deep folder hierarchies for very small collections; use tags or naming conventions instead. For highly dynamic test suites, consider external test runners or code-based frameworks for more control.

Production Patterns

Teams often create folders per API resource (e.g., Users, Orders) and subfolders for actions (e.g., Create, Update). Folder-level auth is set for protected APIs, and folders are run in CI pipelines for automated regression testing.

Connections

File System Hierarchy

Folder hierarchy in Postman mimics file system folder structures.

Understanding file systems helps grasp how nested folders organize and inherit properties.

Object-Oriented Programming (OOP) Inheritance

Folder settings inheritance is similar to class inheritance in OOP.

Knowing inheritance in OOP clarifies how folder-level settings cascade to requests.

Project Management Task Breakdown

Breaking down API tests into folders resembles decomposing projects into tasks and subtasks.

This connection shows how hierarchical organization improves clarity and teamwork across domains.

Common Pitfalls

#1 Creating too many nested folders making navigation confusing.

Wrong approach:

Collection
├── Folder A
│ └── Subfolder A1
│ └── Subfolder A1a
│ └── Subfolder A1a1
│ └── Request 1

Correct approach:

Collection
├── Folder A
│ ├── Subfolder A1
│ └── Request 1

Root cause:

Believing deeper nesting always improves organization without considering usability.

#2 Setting authorization only on folder but overriding it unknowingly in requests.

Wrong approach:

Folder 'User APIs' has Bearer Token auth; Request inside sets No Auth.

Correct approach:

Either set auth only at folder or ensure requests do not override unless needed.

Root cause:

Not understanding that request-level settings override folder-level settings.

#3 Trying to run only some requests inside a folder without separating them.

Wrong approach:

Selecting some requests inside a folder and clicking 'Run' expecting partial execution.

Correct approach:

Create separate folders for different test groups or run requests individually.

Root cause:

Misunderstanding how Postman runs folders as whole units.

Key Takeaways

Folder hierarchy organizes API requests into nested groups, making large collections manageable.

Folders can contain other folders and requests, creating a tree structure that supports scalable organization.

Folder-level settings apply to all contained requests but can be overridden individually.

Running folders lets you execute grouped tests efficiently, supporting automation and collaboration.

Good folder design improves team workflows and reduces errors, but over-nesting can hurt usability.