18.4.3. Creating a REST Resource

@Path("/employees")
public class EmployeeResource {
    private static List<Employee> employees = new ArrayList<>();
    // ...
}

In this chunk, we are defining a Java class named EmployeeResource. The annotation @Path("/employees") indicates that this class will handle HTTP requests targeting the /employees URI. The employees variable is a static list that is used to store instances of the Employee class.

Think of the EmployeeResource class as a library where all the employee records are kept. Just like books in a library, employee details such as their ID, name, and department are stored in the employees list, which is accessible through specific requests to that library.

@GET
@Produces(MediaType.APPLICATION_JSON)
public List<Employee> getEmployees() {
    return employees;
}

This method is marked with @GET, indicating it responds to HTTP GET requests. The annotation @Produces(MediaType.APPLICATION_JSON) specifies that the response data will be in JSON format. When this method is invoked, it returns the current list of employees.

Imagine you are at a restaurant, and you ask the waiter for the menu. This method acts as that waiter, fetching the list of employees (the menu) and presenting it in a format (JSON) that you can easily understand.

@POST
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public Employee addEmployee(Employee employee) {
    employees.add(employee);
    return employee;
}

This method uses the @POST annotation, which handles HTTP POST requests intended for creating new entries. The @Consumes(MediaType.APPLICATION_JSON) annotation denotes that this method expects the request data to be in JSON format. When a new employee is added, this employee object is added to the employees list and then returned.

Think of this method like a clerk at a registration desk who accepts new applicants. When you submit your details (the employee object), the clerk adds your information to the database (the employees list) and hands you a copy of your completed registration form.

@PUT
@Path("/{id}")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public Employee updateEmployee(@PathParam("id") int id, Employee employee) {
    for (Employee e : employees) {
        if (e.getId() == id) {
            e.setName(employee.getName());
            e.setDepartment(employee.getDepartment());
            return e;
        }
    }
    return null;
}

This method is designed to update existing employee information. The @PUT annotation signifies this method handles HTTP PUT requests, which are used for updating resources. The @Path("/{id}") allows the specific employee to be identified by their unique ID passed as a path parameter. If the employee with the given ID is found, their details are updated, and the updated employee object is returned.

Imagine you are revising a report. This method acts like an editor who updates a specific section of the report (the employee details) when you provide new information. If the report doesn't exist, the editor simply can't make any changes.

@DELETE
@Path("/{id}")
public String deleteEmployee(@PathParam("id") int id) {
    employees.removeIf(e -> e.getId() == id);
    return "Employee deleted.";
}

This method is responsible for deleting an employee from the employees list. The @DELETE annotation indicates this method will handle HTTP DELETE requests aimed at removing a resource. The employee to be deleted is identified using the ID passed in the path. Once deleted, a success message is returned.

Think of this method as a process of deleting outdated files from a filing cabinet. When you identify which file (employee) needs to be removed, you take it out and dispose of it, then confirm that the deletion was successful.

--