Quarkus REST Jackson API Building With Resources and DTOs
Build a REST API in Quarkus with the quarkus-rest and quarkus-rest-jackson extensions: resources, DTO records, status codes, exception mappers and a test.

quarkus-rest is the REST engine in Quarkus 3, the successor to RESTEasy Reactive under a simpler name. It uses the Jakarta REST annotations that Java EE developers already know, runs on Vert.x, and does most of its wiring at build time. Paired with quarkus-rest-jackson it turns Java objects into JSON with no further setup. This post builds a small books API: resources, request and response records, status codes, error mapping, input validation and a test. It targets Quarkus 3 on Java 25, and compares with Spring MVC where the comparison helps.
Setup
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-rest</artifactId>
</dependency>
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-rest-jackson</artifactId>
</dependency>
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-hibernate-validator</artifactId>
</dependency>The first two are the REST engine and the JSON provider. Leave out the second and the service starts, then fails on the first request that returns an object, with an error about a missing message body writer. The third enables @Valid on request bodies, covered in validation in Quarkus.
A resource class
@Path("/books")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class BookResource {
public record NewBook(@NotBlank String title, @NotBlank String author) {
}
public record BookView(long id, String title, String author) {
}
private final BookService books;
public BookResource(BookService books) {
this.books = books;
}
@GET
public List<BookView> list(@QueryParam("author") String author) {
return books.search(author).stream().map(BookView::from).toList();
}
@GET
@Path("/{id}")
public BookView get(@PathParam("id") long id) {
return books.find(id)
.map(BookView::from)
.orElseThrow(NotFoundException::new);
}
@POST
public RestResponse<BookView> create(@Valid NewBook body, @Context UriInfo uri) {
Book saved = books.create(body.title(), body.author());
URI location = uri.getAbsolutePathBuilder()
.path(Long.toString(saved.id()))
.build();
return RestResponse.created(location).entity(BookView.from(saved)).build();
}
}The annotations are Jakarta REST: @Path replaces @RequestMapping, @GET replaces @GetMapping, and @PathParam and @QueryParam replace @PathVariable and @RequestParam. Constructor injection works with no @Inject when the class has a single constructor. NotFoundException turns into a 404 without any mapper. RestResponse<T> is the typed counterpart of Spring's ResponseEntity, compared in ResponseEntity: it carries a status, headers and a typed body, so the compiler knows what the endpoint returns.
Map errors in one place
@ServerExceptionMapper
public RestResponse<Map<String, String>> mapConflict(DuplicateBookException e) {
return RestResponse.status(Response.Status.CONFLICT, Map.of("error", e.getMessage()));
}A method with @ServerExceptionMapper, placed in any bean or resource, handles that exception type for every resource. It does the job of @ControllerAdvice with less ceremony. Keep one error shape across the API. The Problem Details extension produces the standard format, and the design reasoning is in error response design. A validation failure from @Valid already becomes a 400 with the violations listed, so you map only your own exceptions.
Test with RestAssured
@QuarkusTest
class BookResourceTest {
@Test
void createsAndReads() {
given()
.contentType("application/json")
.body("{\"title\":\"Effective Java\",\"author\":\"Bloch\"}")
.when()
.post("/books")
.then()
.statusCode(201)
.header("Location", notNullValue());
}
}given(), when() and then() come from RestAssured. The test starts the real application on a test port once for the class, and Dev Services supplies the database container, so the test hits real endpoints through the real HTTP stack. That is a stronger test than calling the resource method directly, because it exercises the annotations, the serialization and the error mapping. Add one test for the validation path, with a blank title expecting 400, and one for the 404. The general testing style is compared with the JUnit-based tests.
Return view records, not entities
Return DTOs from resources. An entity carries lazy associations and persistence state, and serializing it can trigger extra queries or fail outside a transaction with a lazy loading error. A record built from the entity in the service fixes the shape of the API independently of the schema, so renaming a column does not break clients. Accept a separate record for input, as NewBook does, so a client cannot set fields the server owns, such as the id or a creation timestamp.
Threads, blocking and virtual threads
Methods that return plain values run on a worker thread, so blocking calls such as JDBC are safe there. Methods that return Uni or Multi run on the event loop, and blocking inside them stalls the application. Mark a blocking call inside a reactive method with @Blocking. In Quarkus 3 you can also put @RunOnVirtualThread on a method and write blocking code that scales with the number of requests rather than threads. Decide per endpoint: a quick lookup can stay as it is, and a call to a slow service benefits most from virtual threads.
Configuring Jackson for the API
Quarkus builds the ObjectMapper for you, and you adjust it with a customizer bean that implements ObjectMapperCustomizer. Typical changes are to omit null fields, write dates as ISO strings and ignore unknown properties on input. Properties handle the common ones, such as quarkus.jackson.write-dates-as-timestamps=false. Declare your own ObjectMapper bean only if you accept responsibility for all of its settings, and remember that a record field you rename with @JsonProperty changes the contract with every client.
Native image builds add one more rule. Jackson uses reflection, and Quarkus registers the types it can see in your resources automatically. A type that appears only inside a generic collection or a raw Object may need @RegisterForReflection, and the symptom is an empty {} in the response in native mode while the JVM build works. Test the native build once, before you rely on it.
Pagination and filtering
A list endpoint that returns everything works until the table grows. Accept page and size query parameters with sensible defaults and a ceiling, and return the total in a header or a wrapper record. Apply filters in the query, not in memory, and keep the parameter names stable, since they are part of the contract. A client should never be able to ask for a million rows by changing a number in the URL.
Status codes you should return on purpose
Return 201 with a Location header from a create, 204 from a delete that has nothing to say, 404 from a missing id, 409 from a conflict and 400 from invalid input. The mistake to avoid is a 200 with an error in the body, which forces every client to inspect the content before knowing whether the call worked. Compare the design rules in REST API design rules for Java teams.
Validation errors as a clean response
With quarkus-hibernate-validator on the classpath, a constraint violation on a @Valid argument returns a 400 with a default body. To give clients the same format as every other error, map the exception once:
public record Violation(String field, String message) {}
public record ErrorBody(String title, List<Violation> violations) {}
public class ValidationMapper {
@ServerExceptionMapper
public RestResponse<ErrorBody> invalid(ConstraintViolationException e) {
List<Violation> violations = e.getConstraintViolations().stream()
.map(v -> new Violation(lastNode(v.getPropertyPath()), v.getMessage()))
.toList();
return RestResponse.status(Response.Status.BAD_REQUEST, new ErrorBody("Validation failed", violations));
}
private static String lastNode(Path path) {
String name = "";
for (Path.Node node : path) name = node.getName();
return name;
}
}The resource and its request record stay free of error handling:
public record CreateBook(@NotBlank String title, @NotBlank String isbn, @Positive int pages) {}
@POST
public RestResponse<BookView> create(@Valid CreateBook request, @Context UriInfo uri) {
BookView created = books.create(request);
return RestResponse.created(uri.getAbsolutePathBuilder().path(String.valueOf(created.id())).build());
}Customizing Jackson in one place
Quarkus builds its ObjectMapper for you, and you change it by registering a customizer instead of creating your own mapper, which would replace the one the extensions rely on:
@Singleton
public class JsonConfig implements ObjectMapperCustomizer {
@Override
public void customize(ObjectMapper mapper) {
mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
mapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);
mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
}
}With dates written as ISO strings, a LocalDate serializes as 2026-03-14 and not as an array of numbers. Setting FAIL_ON_UNKNOWN_PROPERTIES to false makes the API tolerant of clients that send extra fields, which helps when you evolve a contract, and it also hides typos in a request body, so decide on purpose. Add quarkus-smallrye-openapi and the contract is published at /q/openapi, generated from the resource classes and records, with Swagger UI available in dev mode.
When to choose something else
If you need the Servlet API or a legacy RESTEasy Classic provider, the quarkus-resteasy extensions still exist, in maintenance mode. For a first walk through the project, see the Quarkus tutorial. The reference is the Quarkus REST guide, and Jakarta REST defines the annotations.


