OpenAPI Specification

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/model/Employee.java

The SafeDispatch HQ Administration API is defined using the OpenAPI 3.0.3 specification. This specification serves as the contract for a RESTful service designed for HQ administrators to manage organizational resources including employees, departments, and cross-departmental assignments. The API is hosted locally via HTTPS on port 8443 and implements strict role-based access control (RBAC) to ensure data integrity and security.

Sources: Part1/API/src/main/resources/api-spec.yaml:1-13

API Architecture and Security

The API architecture follows a standard REST pattern, organized around three primary resource types: Employees, Departments, and Assignments. Security is enforced globally using HTTP Basic Authentication. Access to specific HTTP methods is restricted based on the user's role, primarily distinguishing between "MANAGER" and "HR" roles.

Security Implementation

Security constraints are defined in the specification and implemented via Spring Security. While GET operations are generally available to both Managers and HR staff, destructive or state-changing operations (POST, PUT, DELETE) are strictly reserved for the HR role.

The diagram above illustrates the multi-layered security check applied to every incoming API request.
Sources: Part1/API/src/main/resources/api-spec.yaml:15-23, Part1/API/src/main/java/com/example/api/security/SecurityConfig.java:44-52

Data Models and Schemas

The specification defines four core schemas that represent the system's data structures. These schemas ensure consistent data exchange between the client and the server.

Schema	Key Fields	Constraints	Description
Employee	id, name, email, contractType, startDate, salary, role	Required: name, email, contractType, startDate, salary	Represents a staff member.
Department	id, name, budget, location	Required: name, budget, location; budget > 0	Represents an organizational unit.
Assignment	id, employeeId, departmentId, role, accessLevel	Required: employeeId, departmentId	Links an employee to a department.
ErrorResponse	error	String	Standardized error message container.

Sources: Part1/API/src/main/resources/api-spec.yaml:25-104, Part1/API/src/main/java/com/example/api/model/Employee.java:12-32

API Endpoints

Employee Management

Managed by the EmployeeController, these endpoints facilitate the lifecycle of employee records.

Path	Method	Summary	Role Required
/api/employees	GET	List employees (optional department filter)	MANAGER, HR
/api/employees	POST	Create a new employee	HR
/api/employees/{id}	GET	Get employee details by ID	MANAGER, HR
/api/employees/{id}	PUT	Update employee details	HR
/api/employees/{id}	DELETE	Remove an employee	HR
/api/employees/{id}/promote	PUT	Promote employee (+10% salary)	HR

Sources: Part1/API/src/main/resources/api-spec.yaml:108-251, Part1/API/src/main/java/com/example/api/controller/EmployeeController.java:21-82

Department and Assignment Management

These endpoints handle the organizational structure and the mapping of staff to specific departments.

The sequence diagram shows the logic for creating an assignment, which requires validating both the employee and department existence before persistence.
Sources: Part1/API/src/main/java/com/example/api/controller/AssignmentController.java:31-48, Part1/API/src/main/resources/api-spec.yaml:287-313

Business Logic and Validation

The OpenAPI specification defines specific business constraints that are reinforced by the controller logic:

1. Promotion Eligibility: An employee must have a startDate at least 6 months in the past to be eligible for the /promote endpoint. A successful promotion results in a 10% salary increase and a role update (prefixing "Senior ").
2. Department Budget: The budget for a department must be a positive integer. Attempts to create a department with a non-positive budget result in a 400 Bad Request.
3. Referential Integrity: Creating an Assignment requires valid existing employeeId and departmentId.

Sources: Part1/API/src/main/java/com/example/api/controller/EmployeeController.java:88-101, Part1/API/src/main/java/com/example/api/controller/DepartmentController.java:32-35, Part1/API/src/main/java/com/example/api/controller/AssignmentController.java:33-40

Conclusion

The OpenAPI Specification for the SafeDispatch HQ Administration API provides a structured and secure interface for organizational management. By defining clear roles (HR vs. Manager) and strict data models for Employees, Departments, and Assignments, the system ensures that administrative tasks are performed consistently and securely. The integration of business logic, such as promotion eligibility and budget validation, directly into the API flow maintains the integrity of the organizational data.