Employee API Controller

Relevant source files

The following files were used as context for generating this wiki page:

• Part1/API/src/main/java/com/example/api/controller/EmployeeController.java
• Part1/API/src/main/java/com/example/api/service/EmployeeService.java
• Part1/API/src/main/java/com/example/api/model/Employee.java
• Part1/API/src/main/java/com/example/api/repository/EmployeeRepository.java
• Part1/API/src/main/resources/api-spec.yaml
• Part1/API/src/main/java/com/example/api/security/SecurityConfig.java

The EmployeeController serves as the primary interface for managing personnel data within the SafeDispatch HQ Administration system. It exposes a set of RESTful endpoints located under the /api/employees base path, facilitating standard CRUD operations and specialized business logic such as employee promotions.

The controller integrates with the EmployeeRepository to perform data persistence and is subject to security constraints defined in the project's security configuration. Access is restricted based on user roles, typically requiring ROLE_HR for state-changing operations like creating, updating, or deleting employee records.

Sources: EmployeeController.java:14-16, api-spec.yaml:5-9, SecurityConfig.java:44-50

API Endpoints and Operations

The controller provides a comprehensive set of endpoints for managing the lifecycle of an employee. These endpoints support filtering, unique identification, and business-driven state transitions.

Endpoint Summary

Method	Path	Description	Access Level
GET	/api/employees	List all employees (optional department filter)	MANAGER, HR
GET	/api/employees/{id}	Retrieve specific employee by ID	MANAGER, HR
POST	/api/employees	Create a new employee record	HR
PUT	/api/employees/{id}	Update existing employee details	HR
DELETE	/api/employees/{id}	Remove an employee record	HR
PUT	/api/employees/{id}/promote	Apply salary increase and role update	HR

Sources: EmployeeController.java:23-95, api-spec.yaml:104-222, SecurityConfig.java:46-49

Data Flow for Retrieval

When a GET request is made to /api/employees, the controller can optionally filter results by department name. If a department query parameter is provided, it invokes a custom query through the repository; otherwise, it returns all records.

Employee Promotion Logic

The promotion feature is a specialized PUT operation that enforces specific business rules before modifying an employee's record. An employee is only eligible if they have been with the company for at least 6 months.

Promotion Process

1. Validation: The system checks if the employee exists and if their startDate is at least 6 months prior to the current date.
2. Salary Adjustment: A 10% salary increase is applied (calculated as salary * 1.1).
3. Role Update: The employee's role string is prefixed with "Senior ".

Data Model: Employee

The Employee entity defines the structure of the data managed by the controller. It includes personal details, contract information, and relationships to department assignments.

Field	Type	Description	Constraints
id	Long	Primary Key	Generated Identity
name	String	Full name of the employee	-
email	String	Contact email	Must be valid email format
contractType	String	Employment type (e.g., FULL_TIME)	Not Null
startDate	LocalDate	Date of joining	-
salary	Integer	Annual salary	-
role	String	Functional role (e.g., ROLE_HR)	-

Sources: Employee.java:14-38, api-spec.yaml:26-55

Security and Constraints

The EmployeeController is secured using HTTP Basic Authentication. Permissions are strictly enforced based on the request method:

• Read Access: GET requests are accessible to users with either ROLE_MANAGER or ROLE_HR.
• Write Access: POST, PUT, and DELETE requests are restricted exclusively to ROLE_HR.

If an unauthorized user attempts to access these endpoints, the system returns a 401 Unauthorized or 403 Forbidden status.

Sources: SecurityConfig.java:44-50, api-spec.yaml:13-23

Conclusion

The Employee API Controller acts as the central hub for personnel management within the SafeDispatch HQ system. By combining standard persistence operations with strict business eligibility rules for promotions and role-based security, it ensures that employee data is handled accurately and securely.