A REST resource exposes application behavior through HTTP paths and methods. In Quarkus, a Java class can handle requests at a base path, while annotated methods handle particular operations. A reservation service, for example, can expose an availability check without making callers deal directly with its inventory and reservation storage. section 4.2.1
The availability endpoint connects a request to the service’s business logic:
- @Path("reservation") assigns the class the /reservation base path; @GET and @Path("availability") route GET /reservation/availability to the availability method. section 4.2.1
- @RestQuery binds the startDate and endDate query parameters to method arguments. The method retrieves cars, excludes those reserved for the requested dates, and returns the remainder. section 4.2.1
- @Produces(MediaType.APPLICATION_JSON) makes Quarkus serialize REST responses as JSON and set the Content-Type header to application/json. section 4.2.1
Listing 4.7 The source code of the ReservationResource REST resource
package org.acme.reservation.rest;
import java.time.LocalDate;
import java.util.Collection;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import org.acme.reservation.inventory.Car;
import org.acme.reservation.inventory.InventoryClient;
import org.acme.reservation.reservation.Reservation;
import org.acme.reservation.reservation.ReservationsRepository;
import org.jboss.resteasy.reactive.RestQuery;
@Path("reservation") #1
@Produces(MediaType.APPLICATION_JSON)
public class ReservationResource {
private final ReservationsRepository reservationsRepository;
private final InventoryClient inventoryClient;
public ReservationResource(ReservationsRepository reservations,
InventoryClient inventoryClient) { #2
this.reservationsRepository = reservations;
this.inventoryClient = inventoryClient;
}
@GET
@Path("availability") #3
public Collection<Car> availability(@RestQuery LocalDate startDate,
@RestQuery LocalDate endDate) {
// obtain all cars from inventory
List<Car> availableCars = inventoryClient.allCars();
// create a map from id to car
Map<Long, Car> carsById = new HashMap<>();
for (Car car : availableCars) {
carsById.put(car.id, car);
}
// get all current reservations
List<Reservation> reservations = reservationsRepository.findAll();
// for each reservation, remove the car from the map
for (Reservation reservation : reservations) {
if (reservation.isReserved(startDate, endDate)) {
carsById.remove(reservation.carId);
}
}
return carsById.values();
}
}
The ReservationResource listing shows the annotations and the inventory and reservations dependencies together in one endpoint class. section 4.2.1
A resource does not have to be handwritten. For routine database CRUD operations, Quarkus REST Data can generate a JAX-RS resource for a Panache entity. The reservation example declares an interface extending PanacheEntityResource<Reservation, Long> and can set its root path with @ResourceProperties(path = "/admin/reservation"). This route is distinct from the handwritten availability endpoint. section 7.4
For the Hibernate ORM variant, the application needs the REST Data extension, a JDBC driver, and a REST JSON serialization extension. The Hibernate ORM REST Data extension is described as stable; the MongoDB and Hibernate Reactive variants are described as experimental. Quarkus REST implements JAX-RS, and SmallRye OpenAPI can describe an application’s REST resources in a browser-based Swagger API. section 7.4 section 4.10
