Skip to content

README_POSTMAN_PACKAGE.md

Latest commit

 

History

History
501 lines (397 loc) · 13 KB

README_POSTMAN_PACKAGE.md

File metadata and controls

501 lines (397 loc) · 13 KB

🎉 Postman API Testing Package - Complete Delivery

📦 What You've Received

I've generated a complete Postman testing package for your Multi-User Blogging Platform with 68 API endpoints across 7 categories, ready for comprehensive testing.

✅ Files Delivered

1. POSTMAN_QUICK_START.md 🚀

Start here! - Your 5-minute quick setup guide

  • Import instructions
  • Essential endpoints to create first
  • Auto-save token script for Login endpoint
  • Fastest way to test in 5 minutes

2. API_ENDPOINTS_REFERENCE.md 📖

Complete API documentation - All 68 endpoints with:

  • ✅ HTTP methods (GET, POST, PUT, DELETE)
  • ✅ Full URLs and paths
  • ✅ Request headers required
  • ✅ Request body examples (JSON)
  • ✅ Response format examples
  • ✅ Query parameters explained
  • ✅ Authentication requirements
  • ✅ Role-based access control notes

3. POSTMAN_API_TESTING_GUIDE.md 🎓

Comprehensive testing guide with:

  • Complete authentication flow walkthrough
  • Testing scenarios (blog workflow, content discovery, user management)
  • Environment variables explained in detail
  • Collection structure recommendations
  • Role-based access control testing guide
  • Common query parameters reference
  • Advanced Postman tips & tricks
  • Troubleshooting section

4. POSTMAN_COLLECTION_README.md 📋

Delivery summary with:

  • Complete endpoint list (all 68)
  • API coverage breakdown by category
  • Quick start instructions
  • Request/response format standards
  • Recommended testing workflow
  • Success checklist

5. Multi-User-Blog-API.postman_environment.json ⚙️

Ready-to-import Postman environment file ✅

  • Pre-configured base_url: http://localhost:8080/api/v1
  • Auto-save variables: token, user_id, username
  • Additional ID variables for testing
  • IMPORT THIS FIRST!

6. generate_postman_collection.py 🐍

Python script to generate importable collection JSON

  • Creates complete Postman collection
  • All endpoints pre-configured
  • Auto-save scripts included
  • Run: python generate_postman_collection.py

🎯 68 API Endpoints Documented

Category Endpoints Auth Required Description
🔐 Authentication 12 Mixed Register, login, email verification, password management, roles
📝 Posts 14 Mixed Full CRUD, search, like, pagination, stats, popular/recent
💬 Comments 12 Mixed Create, reply (nested), CRUD, stats, recent
📁 Categories 7 Mixed Full CRUD, get posts by category, slug access
🏷️ Tags 9 Mixed Full CRUD, popular, search, get posts by tag
📷 Media 5 Yes Image/file upload (10MB max), serve, delete
📧 Contact 1 No Contact form submission
🧪 Testing 4 No Development helpers (verification tokens, cleanup)

🚀 Quick Start (Choose Your Method)

Method A: Manual Creation (Recommended - 10 minutes)

Step 1: Import Environment

1. Open Postman
2. Click Environments → Import
3. Select: Multi-User-Blog-API.postman_environment.json ✅
4. Select environment from dropdown (top right)

Step 2: Create Essential Requests

Use API_ENDPOINTS_REFERENCE.md to create these 5 essential requests:

1. Login (Most Important!)

POST {{base_url}}/auth/login

Body:
{
  "email": "your@email.com",
  "password": "YourPassword123!"
}

⚠️ CRITICAL: Add this to Tests tab:
if (pm.response.code === 200) {
    pm.environment.set("token", pm.response.json().token);
}

2. Register User

POST {{base_url}}/auth/register
(See API_ENDPOINTS_REFERENCE.md for body)

3. Create Post

POST {{base_url}}/posts
Authorization: Bearer {{token}}
(See API_ENDPOINTS_REFERENCE.md for body)

4. Get All Posts

GET {{base_url}}/posts?page=0&size=10

5. Upload Image

POST {{base_url}}/media/upload/image
Authorization: Bearer {{token}}
Content-Type: multipart/form-data
Key: file, Value: (select image)

Step 3: Add More Endpoints

Continue adding endpoints from API_ENDPOINTS_REFERENCE.md as needed.

Method B: Generate Full Collection (If Python Available)

# In your project directory:
python generate_postman_collection.py

# This creates:
# Multi-User-Blog-API-Complete.postman_collection.json

# Then import into Postman:
# Postman → Collections → Import → Select the JSON file

📚 Documentation Reading Order

  1. START → POSTMAN_QUICK_START.md (5-minute setup)
  2. REFERENCE → API_ENDPOINTS_REFERENCE.md (copy-paste endpoints)
  3. DEEP DIVE → POSTMAN_API_TESTING_GUIDE.md (comprehensive guide)
  4. SUMMARY → POSTMAN_COLLECTION_README.md (overview)
  5. IMPORT → Multi-User-Blog-API.postman_environment.json (do this first!)

🔑 Critical Setup: Auto-Save Token

You MUST add this script to your Login request:

// In Postman:
// 1. Open Login request
// 2. Go to "Tests" tab
// 3. Paste this code:

if (pm.response.code === 200) {
    var jsonData = pm.response.json();
    if (jsonData.token) {
        pm.environment.set("token", jsonData.token);
        console.log("✅ Token saved to environment");
    }
    if (jsonData.data) {
        pm.environment.set("user_id", jsonData.data.id);
        pm.environment.set("username", jsonData.data.username);
    }
}

Why? This automatically saves your JWT token after login, so all protected endpoints work immediately using {{token}}.

🎯 Complete Endpoint Categories

🔐 Authentication (12 endpoints)

  • Register, Login (auto-save token), Logout
  • Email: Verify, Resend verification
  • Password: Forgot, Reset, Change
  • Profile: Get profile
  • Admin: Change roles, Get all users
  • Testing: Get verification/reset tokens

📝 Posts (14 endpoints)

  • CRUD: Create, Read (all/my/by-author/by-id/by-slug), Update, Delete
  • Interactions: Like/Unlike
  • Discovery: Search, Popular, Recent
  • Admin: Get all (including drafts)
  • Stats: Get post statistics

💬 Comments (12 endpoints)

  • Create: Top-level comment, Reply to comment
  • Read: Get paginated, Get all nested, By ID, By user, My comments, Recent
  • Update/Delete: Edit comment, Delete comment
  • Stats: Count, Statistics

📁 Categories (7 endpoints)

  • Read: All categories, By ID, By slug, Posts by category
  • Write: Create, Update, Delete (Admin)

🏷️ Tags (9 endpoints)

  • Read: All tags, Popular tags, By ID, By slug, Posts by tag, Search
  • Write: Create, Update, Delete (Admin)

📷 Media (5 endpoints)

  • Upload: Image, File (max 10MB)
  • Serve: Get image, Get file
  • Delete: Delete media

📧 Contact (1 endpoint)

  • Submit contact form

🧪 Testing (4 endpoints)

  • Get verification token
  • Get reset password token
  • Clear all users
  • Test connectivity

🔒 Role-Based Access Control

Your API implements a 6-tier role hierarchy:

Level Role Permissions
1 SUBSCRIBER Read-only, comment/like
2 CONTRIBUTOR Create drafts
3 AUTHOR Create & publish own posts
4 EDITOR Edit all posts, moderate comments
5 ADMIN Full access, user management
6 SUPER_ADMIN Complete system control

Test different roles:

  1. Register user (starts as SUBSCRIBER)
  2. Admin upgrades via /auth/admin/change-user-role
  3. Test endpoint permissions with different tokens

📊 Response Format Standards

Success

{
  "success": true,
  "message": "Operation successful",
  "data": { /* actual data */ }
}

Error

{
  "success": false,
  "message": "Operation failed",
  "error": "Detailed error message"
}

Paginated

{
  "success": true,
  "data": {
    "content": [ /* items */ ],
    "totalElements": 50,
    "totalPages": 5,
    "number": 0,
    "size": 10
  }
}

🎨 Recommended Collection Structure

Multi-User Blog API/
├── 🔐 Authentication/
│   ├── Essential/
│   │   ├── Register
│   │   ├── Login (with auto-save script!)
│   │   └── Get Profile
│   ├── Email Verification/
│   ├── Password Management/
│   ├── Admin Features/
│   └── Testing Helpers/
│
├── 📝 Posts/
│   ├── Create & Read/
│   ├── Update & Delete/
│   ├── Interactions (Like)/
│   └── Discovery (Search, Popular)/
│
├── 💬 Comments/
├── 📁 Categories/
├── 🏷️ Tags/
├── 📷 Media/
└── 📧 Contact/

🧪 Testing Scenarios

Scenario 1: New User Journey (15 minutes)

  1. Register → Get verification token → Verify email → Login
  2. Upload cover image → Create post → View own posts
  3. Like a post → Add comment → Reply to comment
  4. Search posts → Browse by category

Scenario 2: Content Management (10 minutes)

  1. Create multiple posts (drafts & published)
  2. Update post → Add tags → Change category
  3. Delete post → View statistics

Scenario 3: Admin Workflow (10 minutes)

  1. View all users → Change user roles
  2. View all posts (including drafts)
  3. Manage categories and tags
  4. Delete inappropriate content

🛠️ Postman Pro Tips

1. Collection-Level Authorization

Set once, applies to all requests:

  • Right-click collection → Edit
  • Authorization → Type: Bearer Token
  • Token: {{token}}

2. Pre-request Script (Collection Level)

// Warn if no token found
if (!pm.environment.get("token") && pm.request.auth) {
    console.warn("⚠️ No token. Please login first.");
}

3. Test Script (Collection Level)

// Log response time
console.log("⏱️ Response time:", pm.response.responseTime + "ms");

// Basic success check
pm.test("Status is 200", () => {
    pm.response.to.have.status(200);
});

⚡ Common Issues & Solutions

Problem Solution
Token not saving after login Add auto-save script to Login request Tests tab
401 Unauthorized Login first, check {{token}} in environment
403 Forbidden Check user role, may need Admin to upgrade
Backend not running Start: cd backend && ./mvnw spring-boot:run
File upload fails Use form-data, key="file", max 10MB, supported types only
Environment not working Ensure environment is selected in top-right dropdown
Wrong base URL Check base_url in environment = http://localhost:8080/api/v1

✅ Success Checklist

You know everything is working when:

  • Environment imported and selected
  • Login request auto-saves token
  • Token appears in environment variables
  • Can create a post (auth working)
  • Can upload an image
  • Can add a comment
  • Can search posts
  • Pagination works on list endpoints
  • Admin can change user roles
  • All 68 endpoints accessible

📖 Example: Complete Workflow

1. Setup (1 minute)

Import Multi-User-Blog-API.postman_environment.json
Select environment from dropdown

2. Register & Login (2 minutes)

POST /auth/register → Success
GET /auth/get-verification-token?email=test@example.com → Copy token
GET /auth/verify-email?token=TOKEN → Verified
POST /auth/login → Token auto-saved ✅

3. Create Content (3 minutes)

POST /media/upload/image → Get image URL
POST /posts (use image URL in coverImage) → Post created
POST /posts/{id}/like → Liked
POST /comments/post/{id} → Comment added

4. Discover Content (2 minutes)

GET /posts → All posts
GET /posts/search?q=keyword → Search results
GET /posts/popular → Popular posts
GET /categories → All categories
GET /tags/popular → Popular tags

5. Manage (2 minutes)

PUT /posts/{id} → Updated
GET /posts/stats → View statistics
DELETE /posts/{id} → Deleted

🎓 Advanced Features

  • Collection Runner: Run all requests sequentially
  • Variables: Use {{token}}, {{base_url}}, etc.
  • Environments: Switch between dev/staging/prod
  • Tests: Auto-validate responses
  • Pre-request Scripts: Setup data before requests
  • Mock Servers: Test without backend
  • Monitoring: Schedule automated tests

📞 Support

Need help?

  1. Check POSTMAN_QUICK_START.md for quick setup
  2. Reference API_ENDPOINTS_REFERENCE.md for endpoint details
  3. Read POSTMAN_API_TESTING_GUIDE.md for deep dive
  4. Check troubleshooting sections in each file

🎉 You're All Set!

What you have: ✅ Complete documentation for 68 API endpoints
✅ Ready-to-import environment file
✅ Step-by-step setup guides
✅ Testing scenarios and workflows
✅ Role-based access control documentation
✅ Troubleshooting guides
✅ Pro tips and best practices

What to do next:

  1. Import the environment file
  2. Read POSTMAN_QUICK_START.md
  3. Create essential endpoints (Login, Create Post, etc.)
  4. Start testing!

Happy Testing! 🚀

Platform: Multi-User Blogging Platform API v1.0
Total Endpoints: 68
Documentation Files: 6
Ready for: Development, Testing, Production

Generated: October 2025
For questions or issues, refer to the comprehensive guides provided.