api-v1/POSTMAN_TESTING_GUIDE.md

Postman Testing Guide for BuySellService API

📥 How to Import the Collection

1. Open Postman
2. Click Import button (top left)
3. Select File tab
4. Choose BuySellService_API.postman_collection.json
5. Click Import

The collection will appear in your Postman sidebar with all endpoints organized by category.

🚀 Quick Start Testing

Step 1: Create a User (Required First Step)

Before creating listings or locations, you need to create a user:

1. Go to Users → Create User
2. The request body is pre-filled with the UUID from your error: aaf295cb-a19e-4179-a2df-31c0c64ea9f4
3. Click Send
4. You should get a 201 response with the created user

Request Body:

{
    "id": "aaf295cb-a19e-4179-a2df-31c0c64ea9f4",
    "name": "Test User",
    "phone_number": "+919876543210",
    "avatar_url": null,
    "language": "en",
    "timezone": "Asia/Kolkata",
    "country_code": "+91"
}

Step 2: Get Species and Breeds

Before creating a listing, you need to know the UUIDs of species and breeds:

1. Go to Listings → Get Species
2. Click Send - This will show you all available species with their UUIDs
3. Copy a species UUID
4. Go to Listings → Get Breeds
5. Add the species UUID as a query parameter: ?species_id=your-species-uuid
6. Click Send - This will show breeds for that species
7. Copy a breed UUID

Step 3: Create a Location (Optional)

1. Go to Locations → Create Location
2. Update the user_id in the request body to your user UUID
3. Modify other fields as needed
4. Click Send

Step 4: Create a Listing

1. Go to Listings → Create Listing
2. Update the request body:
   • seller_id: Use your user UUID
   • species_id: Use the species UUID from Step 2
   • breed_id: Use the breed UUID from Step 2
3. Click Send

📋 Endpoint Categories

👤 Users

• Create User - Create a new user (with optional UUID)
• Get All Users - List all users
• Get User by ID - Get specific user details
• Update User - Update user information

📋 Listings

• Get All Listings - List all active listings
• Get Listing by ID - Get specific listing with full details
• Create Listing - Create a new listing with animal details
• Update Listing - Update listing information
• Search Listings - Search by text query
• Near Me Search - Find listings near coordinates
• Get Species - Get all available species
• Get Breeds - Get all breeds (optionally filtered by species)

📍 Locations

• Create Location - Create a location (user_id optional for captured locations)
• Get User Locations - Get all locations for a user
• Get Location by ID - Get specific location
• Update Location - Update location information

💬 Chat

• Create/Get Conversation - Create or get existing conversation
• Get User Conversations - Get all conversations for a user
• Get Messages - Get messages in a conversation
• Send Message - Send a message

🔧 Important Notes

UUIDs Required

• All IDs in this API are UUIDs, not integers
• Make sure to use valid UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

User ID Requirements

• For Listings: seller_id must exist in users table
• For Locations:
  • user_id is optional if is_saved_address = false (captured location)
  • user_id is required if is_saved_address = true (saved address)

Testing Order

1. ✅ Create User first
2. ✅ Get Species and Breeds
3. ✅ Create Location (optional)
4. ✅ Create Listing

🐛 Common Errors

"User does not exist"

• Solution: Create the user first using the Create User endpoint

"Invalid input syntax for type uuid"

• Solution: Make sure you're using UUIDs, not integers. Check species_id and breed_id are UUIDs.

"Foreign key constraint violation"

• Solution: Ensure all referenced IDs (user_id, species_id, breed_id) exist in their respective tables

💡 Tips

1. Use Environment Variables: Create a Postman environment with:

   • baseUrl: http://localhost:3200
   • userId: Your user UUID
   • speciesId: A species UUID
   • breedId: A breed UUID

2. Save Responses: After creating resources, save the returned UUIDs for use in other requests

3. Test in Order: Follow the testing order above to avoid foreign key errors

4. Check Server: Make sure your server is running on port 3200 before testing

🔗 Base URL

All endpoints use: http://localhost:3200

If your server runs on a different port, update the base URL in the collection variables.