Postman Test Collections
Relevant source files
The following files were used as context for generating this wiki page:
- Part1/API/src/main/resources/api-spec.yaml
- Part1/API/src/main/java/com/example/api/controller/EmployeeController.java
- Part1/API/src/main/java/com/example/api/controller/DepartmentController.java
- Part1/API/src/main/java/com/example/api/controller/AssignmentController.java
- Part1/API/src/main/java/com/example/api/security/SecurityConfig.java
- Part1/API/src/main/java/com/example/api/exception/GlobalExceptionHandler.java
Introduction
Postman Test Collections serve as the primary tool for validating the SafeDispatch HQ Administration API. These collections are designed to test the RESTful endpoints used by HQ administrators to manage employees, departments, and assignments within the system. The scope includes verification of CRUD operations, business logic such as employee promotions, and role-based access control (RBAC) enforced via Basic Authentication.
Sources: Part1/API/src/main/resources/api-spec.yaml:4-8, Part1/API/src/main/java/com/example/api/security/SecurityConfig.java:49-56
API Endpoint Structure and Logic
The system is organized into three primary modules: Employees, Departments, and Assignments. Each module provides specific endpoints that Postman collections target for integration and functional testing.
Employee Management
The Employee module handles the lifecycle of staff members. Postman tests must validate that specific fields like contractType, email, and salary are handled correctly during creation and updates.
- List Employees: Supports optional filtering by department name.
- Promotion Logic: A specialized
PUTendpoint applies a 10% salary increase and updates the role to "Senior [Role]" if the employee has been active for more than 6 months.
Sources: Part1/API/src/main/resources/api-spec.yaml:94-118, Part1/API/src/main/java/com/example/api/controller/EmployeeController.java:78-95
Department and Assignment Logic
Departments manage organizational units and budgets, while Assignments link Employees to Departments with specific access levels.
- Department Creation: Requires a positive budget value.
- Assignment Creation: Requires valid
employeeIdanddepartmentId.
Sources: Part1/API/src/main/java/com/example/api/controller/DepartmentController.java:31-34, Part1/API/src/main/java/com/example/api/controller/AssignmentController.java:33-46
Request Flow and Security
The following diagram illustrates the request flow from a Postman client through the security layer to the service controllers.
The API is secured with HTTPS and role-based access control. HR roles have full permissions, while MANAGER roles are restricted to GET operations.
Sources: Part1/API/src/main/java/com/example/api/security/SecurityConfig.java:46-56, Part1/API/src/main/java/com/example/api/exception/GlobalExceptionHandler.java:18-22
Endpoint Specification Table
The Postman collections are built to satisfy the requirements defined in the OpenAPI specification.
| Endpoint | Method | Required Role | Description |
|---|---|---|---|
/api/employees | GET | MANAGER, HR | List all employees (filter by department) |
/api/employees | POST | HR | Create a new employee record |
/api/employees/{id}/promote | PUT | HR | 10% salary increase if tenure > 6 months |
/api/departments | POST | HR | Create department (Budget > 0) |
/api/assignments | POST | HR | Link employee to department |
Sources: Part1/API/src/main/resources/api-spec.yaml:94-278, Part1/API/src/main/java/com/example/api/security/SecurityConfig.java:49-53
Error Handling and Validation
Postman tests should verify that the system returns structured error responses when validation fails. The GlobalExceptionHandler ensures that exceptions are caught and returned as JSON objects containing an "error" key.
Data Models for Testing
Tests must adhere to the JSON structures defined in the API components.
Employee Schema
{
"name": "Jane Smith",
"email": "jane.smith@safedispatch.com",
"contractType": "FULL_TIME",
"startDate": "2023-01-15",
"salary": 35000,
"role": "ROLE_HR"
}
Sources: Part1/API/src/main/resources/api-spec.yaml:34-58
Assignment Request
{
"employeeId": 1,
"departmentId": 2,
"role": "Fleet Coordinator",
"accessLevel": "LEVEL_2"
}
Sources: Part1/API/src/main/java/com/example/api/controller/AssignmentController.java:55-68
Conclusion
Postman Test Collections for the SafeDispatch HQ API are essential for ensuring that employee lifecycle management and organizational assignments function correctly under role-based security. By targeting the endpoints defined in the controllers and validating against the OpenAPI schema, these tests confirm that business rules—such as promotion eligibility and budget constraints—are strictly enforced.