18.4. RESTful API with Java EE (Jakarta EE)

JAX-RS is the standard API for creating RESTful services in Java EE.

JAX-RS, which stands for Java API for RESTful Web Services, is an important component in Java EE that helps developers create RESTful web services. It provides annotations and a framework to handle HTTP requests and responses, allowing developers to focus on the business logic rather than the underlying HTTP details.

Think of JAX-RS like a highway system designed specifically for delivery trucks. Just like how a truck can travel on a highway to deliver goods to various destinations, developers use JAX-RS to send and receive data between clients and servers in a streamlined manner, ensuring that the 'deliveries' are made efficiently without needing to worry about the traffic rules.

<dependency>
  <groupId>javax.ws.rs</groupId>
  <artifactId>javax.ws.rs-api</artifactId>
  <version>2.1</version>
</dependency>

To use JAX-RS in a Java EE project, you need to declare it as a dependency in your pom.xml file if you're using Maven as your build tool. The provided XML snippet specifies the group ID, artifact ID, and version of the JAX-RS API, allowing Maven to retrieve the required libraries automatically. This means you don't have to download the library manually; just adding this dependency makes your project ready to use JAX-RS features.

It's similar to setting up a subscription service. When you subscribe to a magazine (in this case, the JAX-RS API), you just provide your details, and each month, the magazine is delivered right to your door without you needing to go out and buy it every time. Here, the 'subscription' is your dependency declaration in pom.xml.

@Path("/employees")
public class EmployeeResource {
  private static List<Employee> employees = new ArrayList<>();
  @GET
  @Produces(MediaType.APPLICATION_JSON)
  public List<Employee> getEmployees() {
    return employees;
  }
  @POST
  @Consumes(MediaType.APPLICATION_JSON)
  @Produces(MediaType.APPLICATION_JSON)
  public Employee addEmployee(Employee employee) {
    employees.add(employee);
    return employee;
  }
  @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;
  }
  @DELETE
  @Path("/{id}")
  public String deleteEmployee(@PathParam("id") int id) {
    employees.removeIf(e -> e.getId() == id);
    return "Employee deleted.";
  }
}

In this chunk, we see how to define a REST resource using JAX-RS annotations. The class EmployeeResource is mapped to the URL path /employees. Inside this class, we implement various HTTP methods using specific annotations. The @GET annotation is used to retrieve the employee list, @POST to add a new employee, @PUT to update an existing employee identified by an ID, and @DELETE to remove an employee. Each method specifies how it handles data formats like JSON through the @Produces and @Consumes annotations.

Think of the EmployeeResource class as a library where each method is like a different librarian specializing in a task. One librarian (method) retrieves books (employee data), another librarian adds new books (adds employees), another updates book information (updates employee details), and the final librarian removes books from the collection (deletes employees). Each librarian works according to specific requests (HTTP methods) and understands how to handle the library's catalog (data in JSON format).

--