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");
    }
}

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

Response Types

Common Annotations

HTTP Methods

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

Parameter Binding

@RestPath("id")         // URL path parameter
@RestQuery("filter")    // Query string parameter
@RestHeader("auth")     // HTTP header
@RestForm("data")       // Form field

Security

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

Filters & Mapping

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

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);

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);

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.

Documentation

Guides

Step-by-step instructions for common tasks:

• Quick Start - Getting started with Quarkus REST
• Building REST APIs - Creating REST endpoints
• Security Setup - 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
• Edge Cases - Corner cases and error handling

Reference

Detailed API documentation:

Core APIs:

• Filters - Request/response filtering
• Exception Mapping - Error handling
• Response Handling - Response API
• Parameter Binding - Parameter annotations

Features:

• Streaming - SSE and reactive streams
• Multipart - File uploads
• Caching - HTTP caching
• REST Client - Client features
• REST Links - HATEOAS support

Integration:

• Jackson Integration - JSON customization
• Kotlin Serialization - Kotlin JSON support
• Qute Templates - Template engine
• CSRF Protection - CSRF tokens

Configuration:

• Configuration - Build and runtime config
• Conditional Endpoints - Feature flags
• Date Formatting - Temporal types

Advanced:

• Advanced Integration - Extension development
• Resource Utilities - Resource management

Key Features

• Build-Time Optimization: Generates optimized bytecode for faster startup
• Reactive by Default: Seamless Mutiny integration for non-blocking operations
• Security Integration: Built-in RBAC and permission-based access control
• Type-Safe Responses: RestResponse<T> for compile-time type checking
• Declarative REST Clients: Create clients using interfaces with JAX-RS annotations

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. Configure buffer sizes for large payloads
5. 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. Follow the Quick Start Guide
2. Learn Reactive Programming
3. Explore Common Scenarios
4. Review Reference Documentation