Home / Postman setup guide

Step-by-step: building a Postman collection from scratch

Prerequisites

• Download and install Postman
• Ensure your Spring Boot API is running: ./mvnw spring-boot:run
• Verify API is responding: curl http://localhost:8080/customers

Phase 1: Initial Postman setup

1. Create new workspace

1. Open Postman
2. Click Workspaces → Create Workspace
3. Name: API Documentation Projects
4. Description: Collections for technical writing showcases
5. Visibility: Personal (for now)
6. Click Create

2. Create new collection

1. In your workspace, click New → Collection
2. Name: Customer Management API
3. Description:

   Complete collection for testing the Customer Management REST API.
   Demonstrates CRUD operations, batch processing, search functionality, and error handling.
   

4. Click Create

3. Set up environment

1. Click Environments → Create Environment
2. Name: Development
3. Add variables:

   Variable: baseUrl
   Initial Value: http://localhost:8080
   Current Value: http://localhost:8080
   
   Variable: customerID
   Initial Value: CUST001
   Current Value: CUST001
   
   Variable: adminUsername
   Initial Value: testadmin
   Current Value: testadmin
   
   Variable: adminPassword
   Initial Value: admin123
   Current Value: admin123
   

4. Click Save
5. Select the Development environment in the top-right dropdown

Phase 2: Build the collection structure

1. Create folder structure

Right-click on your collection → Add Folder

Folder 1:

• Name: Single Customer CRUD Operations
• Description: Individual customer management operations

Folder 2:

• Name: Multiple Customer Operations
• Description: Batch and search operations

Folder 3:

• Name: Error Testing
• Description: Test error conditions and edge cases

Phase 3: Add requests - Single Customer CRUD

Request 1: Create Customer (POST)

1. Right-click Single Customer CRUD Operations → Add Request
2. Request Name: Create Customer
3. Method: POST
4. URL: /customer
5. Headers:
   • Key: Content-Type, Value: application/json
6. Body: Select raw → JSON, paste:

   {
     "name": "Alice Johnson",
     "id": "",
     "phone": "555-0123",
     "type": "VIP",
     "address": {
       "street": "123 Main St",
       "city": "New York",
       "state": "NY",
       "zipCode": "10001",
       "country": "USA"
     }
   }
   

7. Save the request

Request 2: Get Customer by ID (GET)

1. Add new request to same folder
2. Request Name: Get Customer by ID
3. Method: GET
4. URL: /customer/
5. Headers:
   • Key: Accept, Value: application/json
6. Save

Request 3: Update Customer (PUT)

1. Add new request
2. Request Name: Update Customer (PUT)
3. Method: PUT
4. URL: /customer
5. Headers:
   • Key: Content-Type, Value: application/json
6. Body: raw → JSON:

   {
     "name": "Alice Johnson Updated",
     "id": "",
     "phone": "555-9999",
     "type": "PREMIUM",
     "address": {
       "street": "456 Updated Ave",
       "city": "New York",
       "state": "NY",
       "zipCode": "10002",
       "country": "USA"
     }
   }
   

7. Save

Request 4: Partial Update (PATCH)

1. Add new request
2. Request Name: Partial Update Customer (PATCH)
3. Method: PATCH
4. URL: /customer/
5. Headers:
   • Key: Content-Type, Value: application/json
6. Body: raw → JSON:

   {
     "phone": "555-PATCH",
     "type": "BUSINESS"
   }
   

7. Save

Authentication setup

The Customer Management API uses HTTP Basic Authentication for protected endpoints. DELETE operations require ADMIN role authentication.

Setting up authentication

Method 1: Collection-level authentication (Recommended)

1. Right-click your collection → Edit
2. Go to the Authorization tab
3. Type: Select Basic Auth
4. Username: ``
5. Password: ``
6. Click Save

This applies authentication to ALL requests in the collection. Individual requests can override this if needed.

Method 2: Individual request authentication For requests that need authentication (like DELETE), you can set it per request:

1. Open the request → go to Authorization tab
2. Type: Select Basic Auth
3. Username: ``
4. Password: ``

Request 5: Delete Customer (DELETE)

1. Add new request
2. Request Name: Delete Customer (Admin Only)
3. Method: DELETE
4. URL: /customer/
5. Authorization: (If not set at collection level)
   • Go to Authorization tab
   • Type: Basic Auth
   • Username: ``
   • Password: ``
6. No additional headers or body needed
7. Save

Note: This request requires ADMIN role. Without authentication, it will return 401 Unauthorized.

Phase 4: Add requests - Multiple Customer Operations

Request 6: Batch Create

1. Right-click Multiple Customer Operations → Add Request
2. Request Name: Batch Create Customers
3. Method: POST
4. URL: /customers/batch
5. Headers:
   • Key: Content-Type, Value: application/json
6. Body: raw → JSON:

   [
     {
       "name": "Bob Smith",
       "id": "CUST002",
       "phone": "555-0124",
       "type": "BUSINESS",
       "address": {
         "street": "456 Oak Ave",
         "city": "Boston",
         "state": "MA",
         "zipCode": "02101",
         "country": "USA"
       }
     },
     {
       "name": "Carol Davis",
       "id": "CUST003",
       "phone": "555-0125",
       "type": "INDIVIDUAL",
       "address": {
         "street": "789 Pine St",
         "city": "Seattle",
         "state": "WA",
         "zipCode": "98101",
         "country": "USA"
       }
     }
   ]
   

7. Save

Request 7: Get All Customers

1. Add new request
2. Request Name: Get All Customers (Paginated)
3. Method: GET
4. URL: /customers
5. Params: (Postman will add these to URL automatically)
   • Key: page, Value: 0
   • Key: size, Value: 10
6. Headers:
   • Key: Accept, Value: application/json
7. Save

Request 8: Search by Name

1. Add new request
2. Request Name: Search Customers - by Name
3. Method: GET
4. URL: /customers/search
5. Params:
   • Key: name, Value: Alice
   • Key: page, Value: 0
   • Key: size, Value: 10
6. Headers:
   • Key: Accept, Value: application/json
7. Save

Request 9: Search by Type

1. Add new request
2. Request Name: Search Customers - by Type
3. Method: GET
4. URL: /customers/search
5. Params:
   • Key: type, Value: VIP
   • Key: page, Value: 0
   • Key: size, Value: 10
6. Save

Request 10: Search by Location

1. Add new request
2. Request Name: Search Customers - by Location
3. Method: GET
4. URL: /customers/search
5. Params:
   • Key: city, Value: New York
   • Key: state, Value: NY
   • Key: page, Value: 0Our
   • Key: size, Value: 10
6. Save

Phase 5: Add error testing requests

Request 11: Test 404 Error

1. Right-click Error Testing → Add Request
2. Request Name: Get Non-existent Customer (404)
3. Method: GET
4. URL: /customer/NONEXISTENT
5. Headers:
   • Key: Accept, Value: application/json
6. Save

Request 12: Test 400 Error

1. Add new request
2. Request Name: Create Customer - Invalid Data (400)
3. Method: POST
4. URL: /customer
5. Headers:
   • Key: Content-Type, Value: application/json
6. Body: raw → JSON:

   {
     "name": "",
     "id": "",
     "type": "INVALID_TYPE"
   }
   

7. Save

Request 13: Test Authentication Error (401)

1. Add new request
2. Request Name: Delete Customer - No Auth (401)
3. Method: DELETE
4. URL: /customer/
5. Authorization: Select No Auth (this overrides collection-level auth)
6. Save

This request demonstrates what happens when you try to access a protected endpoint without proper authentication.

Phase 6: Test your collection

1. Test the happy path

1. First: Run Create Customer - should return “Customer added successfully”
2. Then: Run Get Customer by ID - should return customer data
3. Then: Run Get All Customers - should show your customer in the list
4. Then: Run Search by Name with name=Alice - should find your customer

2. Test updates

1. Run Partial Update Customer (PATCH) - should update phone and type
2. Run Get Customer by ID again - verify changes took effect
3. Run Update Customer (PUT) - should replace entire customer
4. Run Get Customer by ID again - verify full replacement

3. Test batch and search

1. Run Batch Create Customers - should create multiple customers
2. Run Get All Customers - should show multiple customers now
3. Try different search requests with various filters

4. Test error conditions

1. Run Get Non-existent Customer (404) - should return 404 error
2. Run Create Customer - Invalid Data (400) - should return validation error
3. Run Delete Customer - No Auth (401) - should return 401 Unauthorized error

5. Test authentication

1. Test DELETE with Authentication:
   • Ensure collection-level authentication is set OR individual DELETE request has auth configured
   • Run Delete Customer (Admin Only) - should return “Customer deleted successfully”
2. Test DELETE without Authentication:
   • Temporarily disable authentication on the DELETE request:
     • Go to request Authorization tab
     • Type: Select No Auth
   • Run the request - should return 401 Unauthorized
   • Re-enable authentication after testing
3. Verify Environment Variables:
   • Check that `` resolves to testadmin
   • Check that `` resolves to admin123
   • You can see resolved values in the request preview

Phase 7: Add pre-request scripts (Advanced)

1. Collection-level script

1. Right-click collection → Edit
2. Go to Pre-request Script tab
3. Add this script:

   // Generate unique customer ID for testing
   pm.globals.set('customerID', 'CUST' + Math.floor(Math.random() * 1000).toString().padStart(3, '0'));
   
   // Set timestamp for testing
   pm.globals.set('timestamp', new Date().toISOString());
   
   console.log('Generated Customer ID:', pm.globals.get('customerID'));
   

4. Save

2. Test with dynamic IDs

1. Run Create Customer - check Console (View → Show Postman Console) to see generated ID
2. Update your Get Customer by ID request to use the dynamic ID if needed

Phase 8: Export your collection

1. Export collection

1. Right-click your collection → Export
2. Choose Collection v2.1 (recommended)
3. Export and save as Customer-Management-API.postman_collection.json

2. Export environment

1. Go to Environments → Click the Development environment
2. Click … → Export
3. Save as Development.postman_environment.json

3. Share your work

Now you have two files to share:

• Customer-Management-API.postman_collection.json - The requests
• Development.postman_environment.json - The environment variables

Others can import both files to get your complete setup.

Phase 9: Documentation integration

1. Generate documentation

1. Click your collection → View Documentation
2. Publish to create shareable docs
3. Or Export as HTML for offline documentation

2. Add request descriptions

For each request, click … → Edit → Add detailed descriptions:

Example for Create Customer:

Creates a new customer with complete profile information.

**Features demonstrated:**
- Nested object handling (Address within Customer)
- Enum validation (CustomerType)
- Input validation and error handling

**Required fields:**
- name: Customer full name
- id: Unique customer identifier (format: CUSTXXX)
- type: Customer type (INDIVIDUAL, BUSINESS, VIP, PREMIUM)

**Optional fields:**
- phone: Contact phone number
- address: Complete address object

Pro tips for technical writers:

1. Organize requests logically

• Group by functionality (CRUD, Search, Batch)
• Order by typical workflow (Create → Read → Update → Delete)
• Include error cases in separate folder

2. Use environment variables

• `` for different environments (dev, staging, prod)
• `` for reusable test data
• and for authentication credentials
• `` for JWT tokens (when applicable)

3. Add comprehensive testing

• Test both success and failure scenarios
• Include edge cases (empty data, invalid formats)
• Test all parameter combinations
• Test authentication: both authenticated and unauthenticated requests
• Test authorization: verify role-based access control works correctly

4. Document everything

• Add descriptions to requests explaining what they test
• Include example responses
• Document required vs optional fields

5. Keep collections updated

• Re-export after changes
• Version your collections (v1.0, v1.1, etc.)
• Test collections regularly to ensure API changes don’t break them

This workflow gives you a professional Postman collection that demonstrates thorough API testing skills - exactly what technical writing positions look for!