or run

tessl search

tessl/maven-io-quarkus--quarkus-resteasy-reactive

tessl install tessl/maven-io-quarkus--quarkus-resteasy-reactive@3.15.0

A Jakarta REST implementation utilizing build time processing and Vert.x for high-performance REST endpoints with reactive capabilities in cloud-native environments.

Building REST APIs

A comprehensive guide to building production-ready REST APIs with Quarkus REST.

Resource Classes

Basic Structure

@Path("/api/items")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class ItemResource {

    @Inject
    ItemService itemService;

    // Endpoints here
}

CRUD Operations

@GET
public List<Item> list() {
    return itemService.findAll();
}

@GET
@Path("/{id}")
public Item get(@RestPath Long id) {
    return itemService.findById(id)
        .orElseThrow(() -> new NotFoundException());
}

@POST
public Response create(Item item) {
    Item created = itemService.create(item);
    return Response.status(201)
        .entity(created)
        .build();
}

@PUT
@Path("/{id}")
public Item update(@RestPath Long id, Item item) {
    return itemService.update(id, item);
}

@DELETE
@Path("/{id}")
public Response delete(@RestPath Long id) {
    itemService.delete(id);
    return Response.noContent().build();
}

Request Handling

Path Parameters

@GET
@Path("/users/{userId}/orders/{orderId}")
public Order getOrder(
    @RestPath Long userId,
    @RestPath Long orderId
) {
    return orderService.findByUserAndId(userId, orderId);
}

Query Parameters

@GET
public List<Item> search(
    @RestQuery String q,
    @RestQuery @DefaultValue("0") int page,
    @RestQuery @DefaultValue("20") int size,
    @RestQuery @DefaultValue("name") String sort
) {
    return itemService.search(q, page, size, sort);
}

Headers

@GET
@Path("/{id}")
public Response get(
    @RestPath Long id,
    @RestHeader("Accept-Language") String language
) {
    Item item = itemService.findById(id, language);
    return Response.ok(item).build();
}

Request Body

@POST
public Response create(
    @Valid CreateItemRequest request
) {
    Item item = itemService.create(request);
    return Response.status(201).entity(item).build();
}

Response Handling

Type-Safe Responses

@GET
@Path("/{id}")
public RestResponse<Item> get(@RestPath Long id) {
    Item item = itemService.findById(id);
    if (item == null) {
        return RestResponse.notFound();
    }
    return RestResponse.ok(item);
}

Custom Status Codes

@POST
@ResponseStatus(201)
public Item create(Item item) {
    return itemService.create(item);
}

Custom Headers

@GET
@Path("/{id}")
@ResponseHeader(name = "X-Total-Count", value = "100")
public List<Item> list() {
    return itemService.findAll();
}

Error Handling

Exception Mappers

@ServerExceptionMapper
public RestResponse<ErrorResponse> handleNotFound(NotFoundException ex) {
    return RestResponse.status(404, new ErrorResponse("Not found"));
}

@ServerExceptionMapper
public RestResponse<ErrorResponse> handleValidation(ValidationException ex) {
    return RestResponse.status(400, new ErrorResponse(ex.getMessage()));
}

Error Response Structure

public class ErrorResponse {
    public String message;
    public String code;
    public Instant timestamp;
    
    public ErrorResponse(String message) {
        this.message = message;
        this.timestamp = Instant.now();
    }
}

Validation

Bean Validation

public class CreateItemRequest {
    @NotBlank
    @Size(min = 3, max = 100)
    public String name;
    
    @NotNull
    @Min(0)
    public BigDecimal price;
    
    @Email
    public String contactEmail;
}

@POST
public Item create(@Valid CreateItemRequest request) {
    return itemService.create(request);
}

Content Negotiation

Multiple Media Types

@GET
@Path("/{id}")
@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
public Item get(@RestPath Long id) {
    return itemService.findById(id);
}

Conditional Responses

@GET
@Path("/{id}")
public Response get(
    @RestPath Long id,
    @HeaderParam("Accept") String accept
) {
    Item item = itemService.findById(id);
    
    if (accept.contains("application/xml")) {
        return Response.ok(item)
            .type(MediaType.APPLICATION_XML)
            .build();
    }
    
    return Response.ok(item)
        .type(MediaType.APPLICATION_JSON)
        .build();
}

Pagination

public class PagedResult<T> {
    public List<T> items;
    public int page;
    public int pageSize;
    public long totalItems;
    public int totalPages;
}

@GET
public PagedResult<Item> list(
    @RestQuery @DefaultValue("0") int page,
    @RestQuery @DefaultValue("20") int size
) {
    return itemService.findPaginated(page, size);
}

Filtering and Sorting

@GET
public List<Item> list(
    @RestQuery Optional<String> category,
    @RestQuery Optional<BigDecimal> minPrice,
    @RestQuery Optional<BigDecimal> maxPrice,
    @RestQuery @DefaultValue("name") String sortBy,
    @RestQuery @DefaultValue("asc") String sortOrder
) {
    return itemService.findFiltered(
        category, minPrice, maxPrice, sortBy, sortOrder
    );
}

Versioning

URI Versioning

@Path("/v1/items")
public class ItemResourceV1 {
    // Version 1 implementation
}

@Path("/v2/items")
public class ItemResourceV2 {
    // Version 2 implementation
}

Header Versioning

@GET
@Path("/{id}")
public Response get(
    @RestPath Long id,
    @RestHeader("API-Version") @DefaultValue("1") int version
) {
    if (version == 2) {
        return Response.ok(itemService.findByIdV2(id)).build();
    }
    return Response.ok(itemService.findById(id)).build();
}

Best Practices

Use Type-Safe Responses: Prefer RestResponse<T> over Response
Validate Input: Always use @Valid for request bodies
Handle Errors Gracefully: Implement exception mappers
Document Your API: Use OpenAPI annotations
Version Your API: Plan for API evolution
Use Pagination: For large result sets
Implement Filtering: Allow clients to filter results
Return Appropriate Status Codes: Follow HTTP semantics

Next Steps

Add Security to your API
Implement Reactive Programming
Build REST Clients
Review Common Scenarios

Version