Postman Collection Best Practices

A collection grows quickly. Ten requests become fifty, and fifty become two hundred. Without habits that keep it tidy, the collection turns into a junk drawer that nobody trusts. Good structure, clear names, and shared rules keep collections useful for months and for new teammates.

The Tidy Workshop Idea

A carpenter hangs each tool on a labeled hook. Finding a hammer takes seconds, and a missing tool is obvious. A well-kept collection offers the same clarity: every request has a place, a name, and a purpose.

  MESSY COLLECTION                 TIDY COLLECTION
  ─────────────────                ─────────────────
  Request 1                        Shop API
  New Request                      ├── 01 Authentication
  test test                        │     └── Login
  copy of copy of login            ├── 02 Products
  getstuff                         │     ├── List Products
  final_FINAL                      │     └── Get Product by ID
                                   └── 03 Orders
                                         ├── Create Order
                                         └── Cancel Order

Naming Rules

Item	Good Name	Weak Name
Collection	Shop API	My Tests
Folder	Orders	Folder 2
Request	Create Order	POST request
Variable	baseUrl, orderId	x, temp1
Environment	Shop Staging	Env copy

Start request names with a verb: Get, Create, Update, Delete. Use one style, such as camelCase for variables, across the whole team.

Structure with Folders

• Group requests by feature or resource, not by who wrote them.
• Prefix folder names with numbers when the run order matters.
• Limit nesting to two or three levels to keep navigation quick.
• Place shared setup requests, such as login, in the first folder.

Document Everything Briefly

Click a collection, folder, or request and use the Documentation or description area. Write short notes in Markdown.

• State the purpose of the collection in two sentences.
• Explain how to select an environment and run the collection.
• List required variables and what each one means.
• Describe parameters and expected responses for each request.

Share Settings at the Top

Collections let you define authorization, scripts, and variables once and apply them to every request below.

  COLLECTION LEVEL
  ├── Authorization : Bearer {{token}}      (requests inherit it)
  ├── Variables     : baseUrl, apiVersion
  └── Scripts       : common tests such as "status code is not 5xx"

A change in one place updates every request. Duplicated settings invite mistakes when one copy gets forgotten.

Write Reusable Tests

Put checks that apply everywhere in the collection-level post-response script.

pm.test("Response is not a server error", function () {
    pm.expect(pm.response.code).to.be.below(500);
});

pm.test("Response time is acceptable", function () {
    pm.expect(pm.response.responseTime).to.be.below(2000);
});

Individual requests then add only their own specific assertions.

Handle Variables and Secrets Carefully

• Replace hard-coded URLs with {{baseUrl}}.
• Keep passwords and keys in current values or the vault.
• Delete variables that no request uses any longer.
• Describe each variable in the environment notes.

Review and Maintain

Habit	Frequency
Run the full collection and fix failures	Weekly or before each release
Remove duplicate and obsolete requests	Monthly
Refresh examples and documentation	After every API change
Review member roles and access	Quarterly

Quick Quality Checklist

• Every request has a clear name and a short description.
• Every request has at least one test.
• No secret appears in shared fields.
• The collection runs from start to finish on a clean environment.
• Folder order matches the intended workflow.

Key Points

• Clear names and folders make collections easy to navigate.
• Collection-level auth, variables, and scripts remove duplication.
• Short documentation saves teammates time.
• Regular reviews keep collections accurate.
• Secrets belong in private storage, never in shared values.