Department 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/DepartmentController.java
• Part1/API/src/main/java/com/example/api/service/DepartmentService.java
• Part1/API/src/main/java/com/example/api/model/Department.java
• Part1/API/src/main/java/com/example/api/repository/DepartmentRepository.java
• Part1/API/src/main/resources/api-spec.yaml
• Part1/API/src/main/java/com/example/api/security/SecurityConfig.java
• Part1/API/src/test/java/com/example/api/DepartmentServiceTest.java

The Department API Controller is a core component of the SafeDispatch HQ Administration API, responsible for managing organizational units within the system. It provides RESTful endpoints to create departments, retrieve department listings, and audit employee placement within specific departments.

This controller acts as the entry point for department-related operations, interacting with the DepartmentRepository and DepartmentService to persist data and enforce business rules, such as budget validation. It is secured via Spring Security, restricting administrative actions like department creation to specific user roles.
Sources: DepartmentController.java:12-16, api-spec.yaml:2-6, SecurityConfig.java:45-50

API Endpoints and Operations

The controller exposes three primary endpoints under the /api/departments base path. These endpoints handle the lifecycle of department resources and provide visibility into the relationship between departments and employees.

Endpoint Summary

Method	Endpoint	Description	Auth Requirement
GET	/api/departments	Retrieves a list of all departments.	ROLE_MANAGER or ROLE_HR
POST	/api/departments	Creates a new department with a positive budget.	ROLE_HR
GET	/api/departments/{id}/employees	Returns all employees currently assigned to a department.	ROLE_MANAGER or ROLE_HR

Sources: DepartmentController.java:23-45, api-spec.yaml:228-278, SecurityConfig.java:47-49

Department Creation Logic

When a new department is created, the controller enforces a business constraint requiring the budget to be a positive value. This validation occurs both at the controller level and within the service layer to ensure data integrity.

The flow above illustrates the security and validation checks performed during department creation.
Sources: DepartmentController.java:31-35, DepartmentService.java:27-30, SecurityConfig.java:48

Data Architecture and Model

The Department entity is a JPA-mapped class that stores basic organizational data and maintains a relationship with employee assignments.

Department Schema

Field	Type	Description	Constraints
id	Long	Unique identifier	Generated Identity
name	String	Name of the department	-
budget	Integer	Financial allocation	Must be positive (@Positive)
location	String	Physical/Geographic location	-
assignments	List	Associated employee links	One-to-Many mapping

Sources: Department.java:10-27, api-spec.yaml:73-95

Relationship Diagram

The Department is linked to Employees through an Assignment entity, allowing for a decoupled architecture where employees can be assigned to different roles within a department.

This diagram represents the structural relationship between departments and other core entities.
Sources: Department.java:21-22, Assignment.java:15-20, Employee.java:32-33

Technical Implementation Details

Service and Repository Integration

The DepartmentController utilizes a DepartmentRepository which includes a custom JPQL query to bridge the gap between departments and employees via the assignment table.

// DepartmentRepository.java:18-20
@Query("SELECT a.employee FROM Assignment a WHERE a.department.id = :deptId")
List<Employee> findEmployeesByDepartmentId(@Param("deptId") Long deptId);

Sources: DepartmentRepository.java:18-20

Security Configuration

Access to the Department API is strictly controlled based on HTTP methods. GET requests are accessible to both Managers and HR staff, while POST requests are restricted to HR.

Validation Handling

The system employs a GlobalExceptionHandler to catch and format errors related to department operations, such as IllegalArgumentException thrown when a budget is non-positive.
Sources: GlobalExceptionHandler.java:24-29, DepartmentServiceTest.java:30-38

Conclusion

The Department API Controller provides a robust interface for managing SafeDispatch's organizational structure. By combining Spring Security for access control, JPA for data persistence, and a dedicated service layer for business logic, it ensures that department data remains consistent and secure. The integration with the Assignment system allows for complex auditing of employee distribution across the company's various locations and budgets.