Quarkus REST

Quarkus REST is a modern Jakarta REST (JAX-RS) implementation built on Vert.x for high-performance, reactive REST endpoints with build-time optimization.

Installation

Maven:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-rest</artifactId>
</dependency>

Gradle:

implementation("io.quarkus:quarkus-rest")

Quick Start

Basic REST Endpoint

import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;

@Path("/hello")
public class HelloResource {
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return "Hello, World!";
    }
}

Reactive Endpoint

import io.smallrye.mutiny.Uni;

@Path("/async")
public class AsyncResource {
    @GET
    public Uni<String> getData() {
        return Uni.createFrom().item("Async response");
    }
}

Secured Endpoint

import jakarta.annotation.security.RolesAllowed;

@Path("/admin")
@RolesAllowed("admin")
public class AdminResource {
    @GET
    public List<User> getUsers() {
        return userService.findAll();
    }
}

Core Concepts

Threading Model

• Reactive methods (Uni, Multi, CompletionStage): Run on I/O threads (event loop)
• Blocking methods (regular return types): Run on worker threads
• Override with @Blocking or @NonBlocking annotations

Request Processing

1. Request received on Vert.x event loop
2. Security checks (if configured)
3. Request filters execute
4. Resource method invoked (I/O or worker thread)
5. Response filters execute
6. Response sent to client

Feature Overview

Common Annotations

HTTP Methods

@GET @POST @PUT @DELETE @PATCH @HEAD @OPTIONS

Parameter Binding

@PathParam("id")        // URL path parameter
@QueryParam("filter")   // Query string parameter
@HeaderParam("auth")    // HTTP header
@FormParam("data")      // Form field
@Context                // Inject context objects

Quarkus Shortcuts

@RestPath("id")         // Shorter @PathParam
@RestQuery("filter")    // Shorter @QueryParam
@RestHeader("auth")     // Shorter @HeaderParam

Security

@RolesAllowed("admin")           // Role-based access
@PermissionsAllowed("doc:read")  // Permission-based access
@Authenticated                    // Require authentication
@PermitAll                        // Allow all users

Filters & Mapping

@ServerRequestFilter      // Request filter method
@ServerResponseFilter     // Response filter method
@ServerExceptionMapper    // Exception to Response mapping

Response Types

Quick Reference

Creating Responses

// Simple return
return "text";
return new User("Alice");

// RestResponse
return RestResponse.ok(user);
return RestResponse.notFound();
return RestResponse.status(201, created);

// Response builder
return Response.ok(entity)
    .header("X-Custom", "value")
    .build();

Error Handling

@ServerExceptionMapper
public Response handleError(MyException ex) {
    return Response.status(400)
        .entity(ex.getMessage())
        .build();
}

Reactive Patterns

// Transform
return repository.findById(id)
    .onItem().transform(entity -> new DTO(entity));

// Error recovery
return service.getData()
    .onFailure().recoverWithItem(defaultValue);

// Retry
return client.call()
    .onFailure().retry().atMost(3);

// Combine
return Uni.combine().all()
    .unis(uni1, uni2, uni3)
    .asTuple();

Documentation Structure

Guides

Step-by-step instructions for common tasks:

• Quick Start - Getting started with Quarkus REST
• Building REST APIs - Creating REST endpoints
• Security Setup - Implementing authentication and authorization
• Reactive Programming - Using Uni and Multi
• REST Clients - Building REST clients

Examples

Real-world usage scenarios:

• Common Scenarios - Typical use cases
• Advanced Patterns - Complex implementations
• Integration Examples - Working with other Quarkus features

Reference

Detailed API documentation:

Core APIs:

• Jakarta REST - Standard JAX-RS features
• Reactive Programming - Mutiny integration
• Security - Authentication and authorization
• Filters - Request/response filtering
• REST Response - Response API
• REST Client - Client features

Features:

• Streaming - SSE and reactive streams
• Multipart Forms - File uploads
• File Uploads - File handling
• Caching - HTTP caching
• Declarative Responses - Response annotations
• Exception Mapping - Error handling
• Parameter Annotations - Parameter binding

Configuration & Integration:

• Configuration - Runtime configuration
• Context Injection - CDI integration
• Compression - HTTP compression
• Observability - Metrics and tracing
• Conditional Endpoints - Dynamic endpoints
• Resource Management - Lifecycle management

Advanced:

• Architecture - Internal architecture
• Handler Chain - Pipeline customization
• Server SPI - Low-level server APIs
• Build SPI - Extension development
• Server Multipart - Multipart processing
• Jackson Serialization - JSON customization
• Qute Integration - Template engine
• REST Data Panache - CRUD generation
• REST Links - HATEOAS support
• WebSockets - WebSocket integration

Key Features

Build-Time Optimization

Quarkus processes REST endpoints at build time, generating optimized bytecode for faster startup and lower memory usage.

Reactive by Default

Seamless integration with Mutiny for non-blocking, reactive programming. Methods returning Uni or Multi automatically run on I/O threads.

Security Integration

Built-in support for role-based and permission-based access control with automatic security context management.

Flexible Filtering

Simplified filter annotations (@ServerRequestFilter, @ServerResponseFilter) with automatic parameter injection and reactive support.

Type-Safe Responses

RestResponse<T> provides type-safe response handling with full control over status, headers, and entity.

Declarative REST Clients

Create REST clients using interfaces with JAX-RS annotations. Supports reactive types, custom headers, and error handling.

Configuration

Common configuration properties:

# Base path for REST endpoints
quarkus.rest.path=/api

# Multipart configuration
quarkus.rest.multipart.input-part.default-charset=UTF-8

# Buffer sizes
quarkus.rest.input-buffer-size=10240
quarkus.rest.output-buffer-size=8191

See Configuration Reference for complete options.

Integration

Quarkus REST integrates with:

• JSON: Jackson or JSON-B for serialization
• XML: JAXB for XML support
• Security: OIDC, JWT, Elytron
• Database: Hibernate Reactive, Panache
• Messaging: Reactive Messaging, Kafka
• Observability: Micrometer, OpenTelemetry
• Templates: Qute template engine

Performance Tips

1. Use reactive types (Uni/Multi) for I/O operations
2. Avoid blocking on I/O threads
3. Use @NonBlocking for fast, non-blocking operations
4. Enable HTTP/2 for better performance
5. Configure buffer sizes for large payloads
6. Use caching annotations for cacheable responses

Getting Help

• Quarkus Guides: https://quarkus.io/guides/
• API Docs: https://javadoc.io/doc/io.quarkus/quarkus-rest
• Community: https://quarkus.io/community/

Next Steps

1. Start with: Quick Start Guide
2. Learn reactive: Reactive Programming Guide
3. Secure your API: Security Setup Guide
4. Explore examples: Common Scenarios
5. Deep dive: Reference Documentation