Learn Quarkus - Validation & Request Handling

#Introduction

An API that accepts external data without validating input is a ticking time bomb. In episodes 5 and 6 you built a REST API and persistence. Now it's time to add the guardrails: input validation at every layer.

Episode 7 covers Jakarta Bean Validation in Quarkus — constraint annotations like @NotBlank and @Email on DTOs, activating validation with @Valid, request and response filters, interceptors, and exception translation so validation errors return a consistent format.

#Jakarta Bean Validation in Quarkus

#Adding the Extension

Hibernate Validator is the reference implementation of Jakarta Bean Validation. Add it with ./mvnw quarkus:add-extension -Dextensions=hibernate-validator.

#Constraint Annotations

Constraints are placed on DTO fields or parameters:

DTO with constraints

import jakarta.validation.constraints.*;
 
public class CreateItemCommand {
 
    @NotBlank(message = "Nama tidak boleh kosong")
    @Size(min = 2, max = 100, message = "Nama harus 2-100 karakter")
    public String nama;
 
    @Size(max = 500)
    public String deskripsi;
 
    @NotNull(message = "Harga wajib diisi")
    @Positive(message = "Harga harus lebih dari nol")
    public double harga;
}

Common constraints: @NotBlank, @NotNull, @Size, @Positive, @Email, @Min, @Max, @Pattern. Custom messages make it easier for clients to understand why a request was rejected.

#@Valid and Payload Validation

#Activating Validation

Without @Valid, the constraints on a DTO are ignored. Place @Valid on the resource method parameter:

Activating validation with @Valid

import jakarta.validation.Valid;
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
 
@Path("/api/items")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public class ItemResource {
 
    @POST
    public Item create(@Valid CreateItemCommand command) {
        return new Item(command.nama, command.deskripsi, command.harga);
    }
 
    public record Item(String nama, String deskripsi, double harga) {}
}

With @Valid CreateItemCommand command, RESTEasy Reactive executes validation before the method is called. If it fails, the request is rejected with status 400.

#Validating Query and Path Parameters

Constraints can also be placed directly on method parameters: @PathParam("id") @Min(1) long id rejects values below the minimum, and @QueryParam("limit") @Max(100) int limit bounds the query. The command curl http://localhost:8080/api/items/0 will return 400 because the id value is below the minimum — validation applies to every kind of parameter.

#Request Filters, Response Filters, and Interceptors

#Request Filters

A filter runs before the resource is called. It's suitable for request logging or adding headers:

Request filter

import jakarta.ws.rs.container.*;
import jakarta.ws.rs.ext.Provider;
 
@Provider
public class RequestLogFilter implements ContainerRequestFilter {
 
    @Override
    public void filter(ContainerRequestContext ctx) {
        System.out.println("Request: " + ctx.getMethod()
            + " " + ctx.getUriInfo().getPath());
    }
}

#Response Filters

A response filter runs after the resource produces a response:

Response filter

import jakarta.ws.rs.container.*;
import jakarta.ws.rs.core.HttpHeaders;
import jakarta.ws.rs.ext.Provider;
 
@Provider
public class HeaderResponseFilter implements ContainerResponseFilter {
 
    @Override
    public void filter(ContainerRequestContext req,
                       ContainerResponseContext res) {
        res.getHeaders().putSingle(HttpHeaders.X_FRAME_OPTIONS, "DENY");
    }
}

res.getHeaders().putSingle(...) adds a header to every response. Filters are the right place for security, logging, and log correlation.

#CDI Interceptors

Besides filters, you can use CDI interceptors to wrap business logic. This pattern was already discussed in episode 4 — for example, recording the execution duration of service methods.

#Exception Translation

#ConstraintViolationException

When validation fails, Hibernate Validator throws an exception. Quarkus provides a built-in 400 response, but you can customize its format with an exception mapper:

Mapper for ConstraintViolationException

import jakarta.validation.ConstraintViolationException;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.ext.ExceptionMapper;
import jakarta.ws.rs.ext.Provider;
import java.util.stream.Collectors;
 
@Provider
public class ValidationExceptionMapper
        implements ExceptionMapper<ConstraintViolationException> {
 
    @Override
    public Response toResponse(ConstraintViolationException ex) {
        String detail = ex.getConstraintViolations().stream()
            .map(v -> v.getPropertyPath() + ": " + v.getMessage())
            .collect(Collectors.joining(", "));
        return Response.status(400)
            .entity(new ErrorResponse("validasi-gagal", detail))
            .build();
    }
 
    public record ErrorResponse(String code, String detail) {}
}

This mapper turns ConstraintViolationException into JSON with status 400 — a format that's easy for clients to parse.

#Testing Validation

Start the application then send an invalid payload with curl -X POST http://localhost:8080/api/items -H "Content-Type: application/json" -d '{"nama":"","harga":-5}'. A request with an empty nama and negative harga is rejected with status 400 and an error body explaining which constraint was violated.

#Wrap-Up

Episode 7 installs validation guardrails in your application: understanding Jakarta Bean Validation with constraint annotations, activating payload validation with @Valid, using request and response filters, and translating validation exceptions into consistent error responses via exception mappers.

Key takeaways:

• Add hibernate-validator to activate Jakarta Bean Validation.
• Place constraints like @NotBlank, @Size, @Email on DTO fields.
• @Valid must be placed on method parameters for constraints to execute.
• Validation also applies to @PathParam and @QueryParam.
• ContainerRequestFilter and ContainerResponseFilter process requests and responses.
• ConstraintViolationException can be mapped to a custom error format.

In episode 8 we'll cover configuration and profiles — application.properties and application.yaml, environment-specific profiles, externalized config from environment variables and secrets, as well as configuration management best practices for production.