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.

Parameter Binding

Quarkus REST provides enhanced parameter binding annotations that simplify REST endpoint development. These annotations offer automatic type conversion, optional naming, and convenient features beyond standard JAX-RS parameter annotations.

Import

import org.jboss.resteasy.reactive.RestQuery;
import org.jboss.resteasy.reactive.RestPath;
import org.jboss.resteasy.reactive.RestHeader;
import org.jboss.resteasy.reactive.RestForm;
import org.jboss.resteasy.reactive.RestCookie;
import org.jboss.resteasy.reactive.RestMatrix;
import org.jboss.resteasy.reactive.Separator;

Annotations

@RestQuery

Binds a method parameter to a query parameter from the request URL.

@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface RestQuery {
    String value() default "";  // Parameter name (defaults to method parameter name)
}

Usage:

@GET
public List<Item> search(@RestQuery String q) {
    // Matches ?q=...
}

@GET
public List<Item> filter(@RestQuery("category") String cat) {
    // Matches ?category=...
}

@GET
public List<Item> paginate(@RestQuery int page, @RestQuery int size) {
    // Matches ?page=10&size=20
}

@RestPath

Binds a method parameter to a path parameter from the @Path template.

@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface RestPath {
    String value() default "";  // Parameter name (defaults to method parameter name)
}

Usage:

@GET
@Path("/{id}")
public Item get(@RestPath String id) {
    // Matches /items/123
}

@GET
@Path("/users/{userId}/orders/{orderId}")
public Order getOrder(@RestPath String userId, @RestPath String orderId) {
    // Matches /users/42/orders/100
}

@GET
@Path("/{id}")
public Item get(@RestPath("id") Long itemId) {
    // Custom name and type conversion
}

@RestHeader

Binds a method parameter to an HTTP header value. Automatically converts camelCase parameter names to kebab-case header names.

@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface RestHeader {
    String value() default "";  // Header name (defaults to parameter name converted to kebab-case)
}

Usage:

@GET
public Response get(@RestHeader String contentType) {
    // Matches Content-Type header (automatic camelCase -> kebab-case)
}

@GET
public Response get(@RestHeader String authorization) {
    // Matches Authorization header
}

@GET
public Response get(@RestHeader("X-Custom-Header") String custom) {
    // Explicit header name
}

@GET
public Response get(@RestHeader("User-Agent") String userAgent) {
    // Standard header
}

@RestForm

Binds a method parameter to a form parameter from application/x-www-form-urlencoded or multipart/form-data request body.

@Target({ElementType.PARAMETER, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface RestForm {
    String value() default "";  // Form field name (defaults to parameter name)
}

Usage:

@POST
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
public Response login(@RestForm String username, @RestForm String password) {
    // Matches form fields username and password
}

@POST
@Consumes(MediaType.MULTIPART_FORM_DATA)
public Response upload(@RestForm("file") FileUpload upload, @RestForm String description) {
    // Multipart form with file and text field
}

// Or use a form bean
public class LoginForm {
    @RestForm
    public String username;

    @RestForm
    public String password;
}

@POST
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
public Response login(LoginForm form) {
    // Automatic form binding
}

@RestCookie

Binds a method parameter to a cookie value.

@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface RestCookie {
    String value() default "";  // Cookie name (defaults to parameter name)
}

Usage:

@GET
public Response get(@RestCookie String sessionId) {
    // Matches cookie named sessionId
}

@GET
public Response get(@RestCookie("JSESSIONID") String session) {
    // Explicit cookie name
}

@RestMatrix

Binds a method parameter to a matrix parameter from the request URL.

@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface RestMatrix {
    String value() default "";  // Parameter name (defaults to parameter name)
}

Usage:

@GET
@Path("/items")
public List<Item> filter(@RestMatrix String color, @RestMatrix String size) {
    // Matches /items;color=red;size=large
}

@Separator

Specifies a separator character for splitting a string parameter into a collection.

@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
public @interface Separator {
    String value() default ",";  // Separator character or string
}

Usage:

@GET
public List<Item> filter(@RestQuery @Separator(",") List<String> tags) {
    // Matches ?tags=java,rest,quarkus
    // Automatically splits into List ["java", "rest", "quarkus"]
}

@GET
public List<Item> filter(@RestQuery @Separator("|") Set<String> categories) {
    // Matches ?categories=books|electronics|toys
}

@GET
public Response process(@RestHeader @Separator(",") List<String> acceptLanguage) {
    // Splits Accept-Language: en-US,en;q=0.9,fr;q=0.8
}

Type Conversion

All binding annotations support automatic type conversion for:

Primitives and wrappers: int, Integer, long, Long, boolean, Boolean, double, Double, etc.
Strings: Direct binding
Enums: Automatic conversion from string to enum constant
Temporal types: LocalDate, LocalDateTime, OffsetDateTime, ZonedDateTime, Instant (use @DateFormat for custom patterns)
Collections: List<T>, Set<T>, SortedSet<T> (with @Separator for splitting)
Arrays: T[] (with @Separator for splitting)
Optional types: Optional<T>

Example:

@GET
public Response filter(
    @RestQuery int page,                    // Auto-convert to int
    @RestQuery Optional<String> search,     // Optional parameter
    @RestQuery Status status,               // Enum conversion
    @RestQuery @Separator(",") List<Long> ids  // Split and convert to List<Long>
) {
    // ...
}

Default Values

Use JAX-RS @DefaultValue annotation to provide default values:

import jakarta.ws.rs.DefaultValue;

@GET
public List<Item> list(
    @RestQuery @DefaultValue("0") int page,
    @RestQuery @DefaultValue("10") int size,
    @RestQuery @DefaultValue("name") String sort
) {
    // ...
}

Comparison with JAX-RS Annotations

RESTEasy Reactive	JAX-RS Standard	Key Difference
`@RestQuery`	`@QueryParam`	Optional name, simpler
`@RestPath`	`@PathParam`	Optional name
`@RestHeader`	`@HeaderParam`	Auto kebab-case conversion
`@RestForm`	`@FormParam`	Works with form beans
`@RestCookie`	`@CookieParam`	Simpler cookie access
`@RestMatrix`	`@MatrixParam`	Simpler matrix params

Both sets of annotations are fully supported and can be used interchangeably. RESTEasy Reactive annotations provide enhanced convenience while maintaining JAX-RS compatibility.

Version

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