Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 30 ยท Organizing Work

Collections, folders and requests

Learn how Postman collections, folders and requests fit together, how auth and scripts are inherited, naming and documentation habits, and the collection JSON format.

A single request is easy to keep track of. Fifty are not. Sooner or later you need to find "the request that creates an order" without scrolling through a long list, run all the order checks together, and share your work with a colleague. Postman's answer is the collection: a named container of requests, optionally split into folders, that you can run, document, share and export as one unit.

A collection is more than a bookmark list. It can carry its own authentication, variables, pre-request scripts and tests, and everything inside inherits them. Understanding that hierarchy is the key to a tidy, low-maintenance test suite. And because a collection is stored as plain JSON, you can also read it as data, which is exactly what the runnable stand-ins in this lesson do.

The Postman app itself cannot run on this site, so the sidebar steps below are read-only. The JavaScript examples are stand-ins that work on a real collection JSON structure, so you see what Postman stores and walks.

The hierarchy

Collection The whole suite or API.
Folder A group, nestable.
Request One call with its tests.

Settings flow downwards: collection, folder, request.

1 / 2

Creating and structuring a collection

In the sidebar, open Collections and click the + (new collection) button. Give it a name, for example Shop API. Then:

  1. Hover the collection, open the three-dot menu and choose Add request or Add folder.
  2. Name every request after what it does, not how it is built.
  3. Drag requests between folders to reorder them. Order matters when you run the collection later.

A structure that scales well mirrors how people think about the API, not how the URLs happen to look:

TEXT
Shop API
  Auth
    Log in
    Refresh token
  Orders
    Create order
    Get order
    Update order
    Delete order
  Products
    List products
    Get product
  Health check

Folders can contain folders, so a big API can use two levels (Orders / Returns). Do not go deeper than two or three levels: a tree that is hard to navigate stops being useful.

Naming conventions that help later

Names show up in the Collection Runner, in reports from the command line and in failing-test messages, so they deserve care.

  • Start requests with the action (Create order, Get order by id), optionally with the method for clarity.
  • Be specific about the case in test suites: Create order - missing quantity returns 400.
  • Number only when order matters: 01 Log in, 02 Create order. Otherwise leave numbers out so inserting a request does not force renaming.
  • Keep names short and unique inside a folder, so a log line identifies exactly one request.

Descriptions and documentation

Every collection, folder and request has a Description field that accepts Markdown. Use it for the facts nobody should have to guess: what the endpoint does, which fields are required, what the authentication expects, what an error looks like. These descriptions become the published documentation (see Saved examples, documentation and mock servers), so writing them as you go costs almost nothing.

Inheritance: configure once

Folders and collections can hold the same things a request can. This is what keeps collections maintainable:

  • Authorization. Set Bearer {{token}} once on the collection; every request that is set to Inherit auth from parent uses it. Set a different type on one folder to override it for that group. See Authentication.
  • Scripts. A collection-level Pre-request script runs before every request in it, then the folder's script, then the request's own. Test scripts at collection level run after every response. This is perfect for shared checks such as "response time is under 1000 ms" or "no 5xx errors".
  • Variables. Collection variables are available to every request inside (the next lessons cover all variable scopes in detail).

The order for scripts is outer to inner before the request is sent and (for tests) the same order afterwards: collection, folder, request. That is why a shared setup step belongs at the top level.

flowchart TD
    C["Collection<br/>auth, scripts, variables"] --> F1["Folder: Orders<br/>(own auth optional)"]
    C --> R3["Request: Health check<br/>auth: No Auth"]
    F1 --> R1["Request: Create order"]
    F1 --> R2["Request: Get order"]

Children inherit from the nearest parent that defines a setting; a request can always override.

Duplicating and reorganizing

To create a variant of a request (say, the same call with an invalid body), use Duplicate in the request's menu instead of rebuilding it, then rename it and change only what differs. Folders can be duplicated the same way, and the Move option relocates a request to another collection. Duplicating is how a single happy-path request grows into a set of negative tests.

A second useful feature is Fork/copy of a whole collection when you want to experiment without touching the shared version. Collaboration features are covered later in Postman Flows, collaboration and AI features.

Exporting and importing collections

Open the three-dot menu on a collection and choose Export, then pick the Collection v2.1 format. You get one .json file you can commit to Git, send to a colleague or run with the command line later. To bring a collection in, use Import (top left of the sidebar) and drop the file, or paste raw JSON or a link.

The file is just JSON. Simplified, but with the real field names, a collection looks like this:

JSON
{
  "info": {
    "name": "Shop API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": { "type": "bearer", "bearer": [{ "key": "token", "value": "{{token}}", "type": "string" }] },
  "item": [
    {
      "name": "Orders",
      "item": [
        {
          "name": "Create order",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/orders",
            "body": { "mode": "raw", "raw": "{\"sku\":\"A1\",\"qty\":2}" }
          }
        }
      ]
    }
  ]
}

Two details matter: a folder is an item that has its own item array, and a request is an item that has a request object. Everything else (event for scripts, auth, variable, description) is optional at any level. Exact field shapes vary slightly between exports, so always treat the exported file from your Postman version as the source of truth.

Exported collections can contain secrets: tokens typed straight into requests, current values of variables, and so on. Review a file before committing it or sending it to anyone.

Walking a collection yourself

Because collections are JSON, a script can read one. That is how command-line tools run them, and how you can build your own reports. The first stand-in prints an outline of a collection and counts folders and requests.

JS Outline a collection tree

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second stand-in does what Postman's runner does before it starts: it flattens the tree into the run order (depth first, folder by folder) and works out which level each request inherits its authorization from.

JS Flatten run order and inherited auth

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Habits of well-kept collections

  • One collection per API or per test suite, not one per developer.
  • Put shared auth, headers and scripts at the top; keep individual requests almost empty.
  • Use variables ({{baseUrl}}) for hosts and ids, never hard-coded values.
  • Describe what each folder is for in two lines of Markdown.
  • Delete experiments. A collection with forty unnamed New Request items is a liability.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In the exported collection JSON, how can you tell a folder from a request?

    Both are entries of an item array. Nested item means folder; a request object means request.
  2. 2. A collection uses Bearer {{token}}. One request must be public. What do you do?

    A request can override what it would inherit. No Auth on that one request leaves everything else untouched.
  3. 3. Where should a shared check such as 'response time under 1000 ms' live?

    Collection-level scripts run for every request inside, so the check is written once and applies everywhere.
  4. 4. Why review an exported collection before sharing it?

    Exports are plain JSON. Secrets typed into requests or variables travel with the file.

Summary

  • A collection holds requests and folders; folders can nest and can be duplicated, moved and reordered.
  • Authorization, scripts and variables can be set at collection or folder level and are inherited; the nearest definition wins.
  • Name requests by their action, and document folders and requests with Markdown descriptions.
  • Export as Collection v2.1 JSON to share, version in Git or run elsewhere; review it for secrets first.
  • A collection is just a tree of item entries, which a script can walk.

Next: make the same collection work against several servers with Environments and variables.