Design an Employee Search API.

package com.example.employeesearch;

import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.format.annotation.DateTimeFormat;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Service;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.server.ResponseStatusException;

import java.time.LocalDate;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Comparator;
import java.util.List;
import java.util.Locale;

@SpringBootApplication
public class EmployeeSearchApplication {

    public static void main(String[] args) {
        SpringApplication.run(EmployeeSearchApplication.class, args);
    }

    @Bean
    CommandLineRunner seed(EmployeeService service) {
        return args -> service.addAll(List.of(
                new Employee(1L, "Ava", "Patel", "ava.patel@example.com", "Engineering", "Backend Engineer", "Austin", true, LocalDate.of(2022, 4, 18)),
                new Employee(2L, "Noah", "Kim", "noah.kim@example.com", "Engineering", "Frontend Engineer", "Seattle", true, LocalDate.of(2021, 9, 2)),
                new Employee(3L, "Mia", "Chen", "mia.chen@example.com", "HR", "Recruiter", "Dallas", false, LocalDate.of(2020, 2, 10)),
                new Employee(4L, "Liam", "Singh", "liam.singh@example.com", "Finance", "Analyst", "Chicago", true, LocalDate.of(2023, 1, 5)),
                new Employee(5L, "Emma", "Brown", "emma.brown@example.com", "Engineering", "QA Engineer", "Austin", false, LocalDate.of(2019, 7, 22)),
                new Employee(6L, "Ethan", "Garcia", "ethan.garcia@example.com", "Support", "Support Lead", "Phoenix", true, LocalDate.of(2024, 3, 14))
        ));
    }
}

record Employee(Long id,
                String firstName,
                String lastName,
                String email,
                String department,
                String title,
                String city,
                boolean active,
                LocalDate hiredDate) {
}

record EmployeeSearchResponse(List<Employee> items,
                              int page,
                              int size,
                              long totalElements,
                              int totalPages,
                              boolean hasNext) {
}

record ApiError(String error, String message) {
}

@Service
class EmployeeService {

    private final List<Employee> employees = new ArrayList<>();

    public synchronized void addAll(Collection<Employee> data) {
        employees.addAll(data);
    }

    public EmployeeSearchResponse search(String q,
                                         String department,
                                         Boolean active,
                                         LocalDate hiredAfter,
                                         int page,
                                         int size,
                                         String sortBy,
                                         String sortDir) {

        // The API must defend itself from giant pages and negative indexes.
        if (page < 0) {
            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "page must be >= 0");
        }
        if (size < 1 || size > 100) {
            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "size must be between 1 and 100");
        }

        String normalizedQuery = q == null ? null : q.trim().toLowerCase(Locale.ROOT);
        String normalizedDepartment = department == null ? null : department.trim().toLowerCase(Locale.ROOT);

        Comparator<Employee> comparator = comparatorFor(sortBy);
        if ("desc".equalsIgnoreCase(sortDir)) {
            comparator = comparator.reversed();
        } else if (!"asc".equalsIgnoreCase(sortDir)) {
            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "sortDir must be asc or desc");
        }

        List<Employee> filtered = employees.stream()
                .filter(employee -> matches(employee, normalizedQuery, normalizedDepartment, active, hiredAfter))
                .sorted(comparator.thenComparing(Employee::id))
                .toList();

        long totalElements = filtered.size();
        int totalPages = (int) Math.ceil(totalElements / (double) size);
        int fromIndex = Math.min(page * size, filtered.size());
        int toIndex = Math.min(fromIndex + size, filtered.size());

        // Copy the page so callers cannot accidentally mutate the internal list view.
        List<Employee> items = List.copyOf(filtered.subList(fromIndex, toIndex));
        boolean hasNext = toIndex < filtered.size();

        return new EmployeeSearchResponse(items, page, size, totalElements, totalPages, hasNext);
    }

    private boolean matches(Employee employee,
                            String query,
                            String department,
                            Boolean active,
                            LocalDate hiredAfter) {
        if (active != null && employee.active() != active) {
            return false;
        }
        if (department != null && !employee.department().equalsIgnoreCase(department)) {
            return false;
        }
        if (hiredAfter != null && !employee.hiredDate().isAfter(hiredAfter)) {
            return false;
        }
        if (query == null || query.isBlank()) {
            return true;
        }

        String haystack = (employee.firstName() + " " + employee.lastName() + " " + employee.email() + " " + employee.department() + " " + employee.title() + " " + employee.city())
                .toLowerCase(Locale.ROOT);
        return haystack.contains(query);
    }

    private Comparator<Employee> comparatorFor(String sortBy) {
        String key = sortBy == null ? "lastname" : sortBy.trim().toLowerCase(Locale.ROOT);

        // Whitelisting sort fields prevents bad input and keeps the API predictable.
        return switch (key) {
            case "firstname" -> Comparator.comparing(Employee::firstName, String.CASE_INSENSITIVE_ORDER);
            case "lastname" -> Comparator.comparing(Employee::lastName, String.CASE_INSENSITIVE_ORDER);
            case "department" -> Comparator.comparing(Employee::department, String.CASE_INSENSITIVE_ORDER);
            case "title" -> Comparator.comparing(Employee::title, String.CASE_INSENSITIVE_ORDER);
            case "city" -> Comparator.comparing(Employee::city, String.CASE_INSENSITIVE_ORDER);
            case "hireddate" -> Comparator.comparing(Employee::hiredDate);
            case "id" -> Comparator.comparing(Employee::id);
            default -> throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Unsupported sortBy: " + sortBy);
        };
    }
}

@RestController
@RequestMapping("/api/employees")
class EmployeeController {

    private final EmployeeService service;

    EmployeeController(EmployeeService service) {
        this.service = service;
    }

    @GetMapping("/search")
    public EmployeeSearchResponse search(
            @RequestParam(required = false) String q,
            @RequestParam(required = false) String department,
            @RequestParam(required = false) Boolean active,
            @RequestParam(required = false) @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate hiredAfter,
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size,
            @RequestParam(defaultValue = "lastName") String sortBy,
            @RequestParam(defaultValue = "asc") String sortDir) {

        return service.search(q, department, active, hiredAfter, page, size, sortBy, sortDir);
    }
}

@RestControllerAdvice
class ApiExceptionHandler {

    @ExceptionHandler(ResponseStatusException.class)
    public ResponseEntity<ApiError> handle(ResponseStatusException ex) {
        String message = ex.getReason() == null ? "Bad request" : ex.getReason();
        return ResponseEntity.status(ex.getStatusCode())
                .body(new ApiError(ex.getStatusCode().toString(), message));
    }
}