Postman Collections and Request Organization

Making individual API requests is easy. Organizing hundreds of requests for a real project is where Postman truly shines. Collections transform scattered requests into a structured, documented, shareable API testing workspace.

---

1. What Are Collections?

A collection is a group of related API requests organized together. Think of it like a folder system for your API tests.

graph TD
    A["Postman Workspace"] --> B["Collection: My App API"]
    A --> C["Collection: Third-Party APIs"]

    B --> D["📁 Authentication"]
    B --> E["📁 Users"]
    B --> F["📁 Posts"]
    B --> G["📁 Admin"]

    D --> D1["POST Login"]
    D --> D2["POST Register"]
    D --> D3["POST Refresh Token"]

    E --> E1["GET All Users"]
    E --> E2["GET User by ID"]
    E --> E3["PATCH Update User"]
    E --> E4["DELETE User"]

    F --> F1["GET All Posts"]
    F --> F2["POST Create Post"]
    F --> F3["PUT Update Post"]

    style A fill:#4f46e5,color:#fff
    style B fill:#0891b2,color:#fff
    style C fill:#0891b2,color:#fff

---

2. Creating a Collection

1. Click Collections in the left sidebar
2. Click the + button
3. Name your collection: "REST API Course - Practice"
4. Add a description explaining the API and its purpose

Collection Description (Markdown Supported)

# REST API Course - Practice Collection

Base URL: `https://jsonplaceholder.typicode.com`

This collection contains all the requests for the REST API course exercises.

## Endpoints Covered
- Users CRUD
- Posts CRUD  
- Comments
- Todos

---

3. Organizing with Folders

Good organization makes collections usable months or years later.

Organize by Resource

📁 Users
  ├── GET List All Users
  ├── GET Get User by ID
  ├── POST Create User
  ├── PUT Update User
  ├── PATCH Update User Email
  └── DELETE Delete User

📁 Posts
  ├── GET List All Posts
  ├── GET Get Post by ID
  ├── GET Get Posts by User
  ├── POST Create Post
  └── DELETE Delete Post

Organize by Workflow

📁 1. Authentication
  ├── POST Register
  └── POST Login

📁 2. User Management
  ├── GET My Profile
  └── PATCH Update Profile

📁 3. Content Management
  ├── POST Create Post
  ├── GET My Posts
  └── DELETE Remove Post

---

4. Documenting Requests

Each request can have documentation:

Request Description

Add a description to every saved request explaining:

• What it does
• When to use it
• Required parameters or body
• Expected response

Example description for "Create Post":

Creates a new blog post for the authenticated user.

**Required Body Fields:**
- `title` (string) - Post title, 3-200 characters
- `body` (string) - Post content  
- `userId` (integer) - Author's user ID

**Optional Fields:**
- `tags` (array) - List of tag strings

**Expected Response:** 201 Created

---

5. Request Pre-Scripts and Tests

Postman lets you run JavaScript before a request (pre-script) and after it (test):

Pre-Request Script Example

// Set current timestamp in a variable
pm.variables.set("timestamp", new Date().toISOString());

Test Script Example

// Verify status code
pm.test("Status is 200", function () {
    pm.response.to.have.status(200);
});

// Verify response has required fields
pm.test("Response has user name", function () {
    var jsonData = pm.response.json();
    pm.expect(jsonData.name).to.not.be.undefined;
});

// Verify response time
pm.test("Response time under 500ms", function () {
    pm.expect(pm.response.responseTime).to.be.below(500);
});

---

6. Running Collections

Collection Runner

1. Click the Run button on your collection
2. Select which requests to include
3. Set the number of iterations
4. Click Run Collection

The runner executes all requests in order and shows pass/fail results for each test.

Use Cases for Collection Runner

Scenario	How to Set Up
Smoke test	Run all GET requests to verify API is up
CRUD test	Run Create → Read → Update → Delete in order
Load testing	Set iterations to 100+
Regression testing	Run after any API change

---

7. Exporting and Importing

Export a Collection

1. Right-click the collection
2. Select Export
3. Choose format v2.1 (recommended)
4. Save the .json file

Import a Collection

1. Click Import in the toolbar
2. Drag and drop the .json file
3. All requests are restored

Version Control

Export your collection and commit it to Git:

# In your project repository
mkdir postman/
# Save exported collection to postman/
git add postman/rest-api-course.postman_collection.json
git commit -m "Add Postman collection for API testing"

This lets teammates import and use the same collection.

---

Summary and Key Takeaways

1. Collections organize related requests into a structured workspace.
2. Use folders to group by resource or workflow.
3. Document every request with descriptions and expected responses.
4. Test scripts validate responses automatically.
5. The Collection Runner executes all requests for automated testing.
6. Export collections to share with teammates or store in Git.

---

Lesson Review Quiz