Working with Collections

# CHAPTER 11

Working with Collections #

1. Introduction #

Leaving all your requests in unsaved tabs is a recipe for disaster. As an API grows, you might end up testing hundreds of endpoints. To manage this complexity, Postman relies on Collections. Collections are the backbone of Postman; they are folders that store and group your API requests. In this chapter, we will learn how to create collections, organize them with sub-folders, and understand how collections inherit authorization and variables.

2. Learning Objectives #

By the end of this chapter, you will be able to:

• Create a new Postman Collection.

• Save requests directly into specific collections.

• Organize complex APIs using nested sub-folders.

• Add markdown documentation to your collections.

• Understand how Collections share Authorization settings to save time.

3. Beginner-Friendly Explanation #

Imagine a physical filing cabinet.

• A Workspace is the room the cabinet is in.

• A Collection is a specific drawer in the cabinet (e.g., "E-Commerce API").

• Folders are the manila dividers inside the drawer (e.g., "Users", "Products", "Orders").

• Requests are the individual sheets of paper inside those folders.

If you don't use collections, you just have a massive pile of unorganized papers on your desk. By creating a Collection, you make your API tests easily searchable, shareable, and executable as a group.

4. Real-World Examples #

• Modular Testing: A QA team has a "Regression Testing" collection. Inside, it has folders for "Authentication Tests", "Payment Tests", and "Profile Tests". They can run the entire collection at once to verify the whole system.

• Client Onboarding: A company builds a public API. Instead of writing a 100-page PDF manual, they publish a "Postman Collection" that clients can download, which contains fully configured examples of every single API request.

5. Step-by-Step Tutorials (Building a Collection) #

Let's build a collection for our fake API tests.

Step 1: Create the Collection

1. 1. Look at the left Sidebar and ensure you are on the Collections tab.

1. 2. Click the + button (or "New" -> Collection).

1. 3. A new collection appears. Name it JSONPlaceholder API.

1. 4. Press Enter.

Step 2: Add Folders

1. 1. Hover your mouse over the new JSONPlaceholder API collection in the sidebar.

1. 2. Click the three dots ... (More Actions menu) that appear next to the name.

1. 3. Select Add Folder. Name the folder Users.

1. 4. Repeat this to create a second folder named Posts.

Step 3: Save a Request into the Folder

1. 1. Open a new request tab. Enter a GET request for https://jsonplaceholder.typicode.com/users.

1. 2. Click the Save button (Ctrl+S or Cmd+S).

1. 3. A dialog box appears. Change the Request Name from "Untitled Request" to Get All Users.

1. 4. In the bottom half of the dialog, browse your collections. Click JSONPlaceholder API, then click the Users folder.

1. 5. Click the big blue Save to Users button.

6. Collection Variables #

In the previous chapter, we learned about Environment Variables. Collection Variables work exactly the same way, but they are glued to the collection itself.

• If you have an API key that is *only* used for this specific collection, store it as a Collection Variable.

• To set one, click on the Collection name in the sidebar, look at the main screen, and click the Variables tab.

7. Collection-Level Authorization (Crucial Feature) #

Imagine you have 50 requests in a folder, and all of them require a Bearer Token. Do you manually add the Authorization header to all 50 requests? NO.

1. 1. Click on the Folder (or Collection) name in the sidebar.

1. 2. Go to the Authorization tab.

1. 3. Set the Type to Bearer Token and enter your token.

1. 4. Go to any individual request inside that folder. In its Authorization tab, ensure it is set to "Inherit auth from parent".

Now, all 50 requests automatically use the folder's token!

8. Documenting Collections #

If you click on a Collection or Folder, there is an overview page. You can add descriptions using standard Markdown. A well-documented collection explains to other developers what the API does, what the prerequisite variables are, and how to use it.

9. Best Practices #

• Never save "Untitled Requests": Always give your requests descriptive names like "Create New User" or "Fetch Invoice by ID". POST /users is not a good request name because the URL might change.

• Group by Resource: Structure your folders based on the API resource (e.g., /users endpoints go in the Users folder, /orders endpoints go in the Orders folder).

• Inherit Everything: Always utilize Collection-level Authorization and Pre-request scripts. Never duplicate logic across 10 requests if it can be placed at the parent folder level.

10. Common Mistakes #

• Losing the Save Location: When clicking "Save", beginners often accidentally save a request to the root of the Collection rather than placing it in the correct sub-folder. You can easily drag and drop requests in the sidebar to fix this.

• Too many collections: Don't create a new collection for every minor feature. Keep related APIs in a single collection and use folders to divide features.

11. Mini Exercises #

1. 1. What feature allows a single token to be applied to every request inside a folder automatically?

1. 2. Create a folder called Comments inside your JSONPlaceholder API collection.

12. Coding/Testing Challenges #

Challenge 1: Create a new request that POSTs data to https://jsonplaceholder.typicode.com/posts. Name the request Create New Post. Save this request into the Posts folder you created earlier. Verify it appears correctly in the left sidebar.

13. MCQs with Answers #

14. Interview Questions #

• Q: Explain how you would organize a complex API with 100 endpoints in Postman.

• Q: Explain the concept of "Inheritance" in Postman Collections regarding Authentication.

• Q: When would you choose to use a Collection Variable over an Environment Variable?

15. FAQs #

Q: Can I share a collection with someone else? A: Yes! You can share collections within a Team Workspace, or you can Export a collection as a JSON file and email it to someone. They can then Import that JSON file into their own Postman.

16. Summary #

In this chapter, we brought order to the chaos of API testing. We learned how to create Collections and sub-folders to logically organize our requests. We explored the massive time-saving feature of "Inheritance," allowing folders to pass down Authorization headers to all their child requests automatically. Finally, we learned the importance of naming and documenting our requests for a professional workflow.

17. Next Chapter Recommendation #

We have mentioned "Authorization" several times, but what exactly does it entail? Proceed to Chapter 12: Authentication in Postman to learn how to unlock protected APIs using API Keys, Basic Auth, and Bearer Tokens.