0
# Quarkus Reactive Routes
1

2
Quarkus Reactive Routes is a REST framework offering a declarative route model to define non-blocking endpoints as an alternative to traditional JAX-RS resources. It provides annotation-driven HTTP endpoint creation with comprehensive support for reactive programming patterns, parameter injection, request filtering, and streaming responses.
3

4
## Package Information
5

6
- **Package Name**: quarkus-reactive-routes
7
- **Package Type**: maven
8
- **Group ID**: io.quarkus
9
- **Artifact ID**: quarkus-reactive-routes
10
- **Language**: Java
11
- **Installation**: Add to your Quarkus project's `pom.xml`:
12

13
```xml
14
<dependency>
15
    <groupId>io.quarkus</groupId>
16
    <artifactId>quarkus-reactive-routes</artifactId>
17
</dependency>
18
```
19

20
## Core Imports
21

22
```java
23
import io.quarkus.vertx.web.Route;
24
import io.quarkus.vertx.web.Route.HttpMethod;
25
import io.quarkus.vertx.web.RouteBase;
26
import io.quarkus.vertx.web.Param;
27
import io.quarkus.vertx.web.Header;
28
import io.quarkus.vertx.web.Body;
29
import io.quarkus.vertx.web.RoutingExchange;
30
```
31

32
## Basic Usage
33

34
```java
35
import io.quarkus.vertx.web.Route;
36
import io.quarkus.vertx.web.Route.HttpMethod;
37
import io.quarkus.vertx.web.Param;
38
import io.quarkus.vertx.web.RoutingExchange;
39

40
import jakarta.enterprise.context.ApplicationScoped;
41

42
@ApplicationScoped
43
public class UserRoutes {
44

45
    @Route(path = "/users", methods = HttpMethod.GET)
46
    public String listUsers() {
47
        return "List of users";
48
    }
49

50
    @Route(path = "/users/:id", methods = HttpMethod.GET)
51
    public String getUser(@Param("id") String userId, RoutingExchange exchange) {
52
        return "User: " + userId;
53
    }
54

55
    @Route(path = "/users", methods = HttpMethod.POST, consumes = "application/json")
56
    public String createUser(@Body User user) {
57
        return "Created user: " + user.getName();
58
    }
59
}
60
```
61

62
## Architecture
63

64
Quarkus Reactive Routes is built around several key components:
65

66
- **Annotation-Driven Routes**: `@Route` and related annotations for declarative endpoint definition
67
- **Parameter Injection**: Automatic extraction of request parameters, headers, and body content
68
- **Reactive Responses**: Full support for `Uni<T>` and `Multi<T>` return types for asynchronous processing
69
- **Request Filtering**: `@RouteFilter` for implementing cross-cutting concerns
70
- **Streaming Support**: Built-in support for Server-Sent Events, JSON streaming, and NDJSON
71
- **Context Access**: `RoutingExchange` interface providing comprehensive request/response manipulation
72

73
## Capabilities
74

75
### Route Declaration
76

77
Core functionality for defining HTTP endpoints using declarative annotations. Supports path-based and regex-based routing with comprehensive HTTP method and content-type configuration.
78

79
```java { .api }
80
@Route(
81
    path = "/api/users/:id",
82
    methods = HttpMethod.GET,
83
    produces = "application/json",
84
    consumes = "application/json",
85
    type = Route.HandlerType.NORMAL,
86
    order = 100
87
)
88
public String handleRequest() { return "response"; }
89

90
@RouteBase(
91
    path = "/api/v1",
92
    produces = {"application/json"},
93
    consumes = {"application/json"}
94
)
95
public @interface RouteBase {
96
    String path() default "";
97
    String[] produces() default {};
98
    String[] consumes() default {};
99
}
100
```
101

102
[Route Declaration](./route-declaration.md)
103

104
### Parameter Injection
105

106
System for extracting request data including path parameters, query parameters, HTTP headers, and request body content with automatic type conversion and validation support.
107

108
```java { .api }
109
public String handleRequest(
110
    @Param("id") String userId,
111
    @Param("limit") Optional<String> limit,
112
    @Header("Authorization") String authHeader,
113
    @Body User userData
114
) { return "processed"; }
115
```
116

117
[Parameter Injection](./parameter-injection.md)
118

119
### Request Context and Exchange
120

121
Comprehensive interface for accessing and manipulating HTTP request and response objects, providing both low-level Vert.x access and high-level convenience methods.
122

123
```java { .api }
124
public interface RoutingExchange {
125
    io.vertx.ext.web.RoutingContext context();
126
    io.vertx.core.http.HttpServerRequest request();
127
    io.vertx.core.http.HttpServerResponse response();
128
    Optional<String> getParam(String name);
129
    Optional<String> getHeader(CharSequence name);
130
    io.vertx.core.http.HttpServerResponse ok();
131
    void ok(String chunk);
132
    io.vertx.core.http.HttpServerResponse serverError();
133
    io.vertx.core.http.HttpServerResponse notFound();
134
}
135
```
136

137
[Request Context](./request-context.md)
138

139
### Reactive Streaming
140

141
Support for reactive response types including `Uni<T>` for single asynchronous values and `Multi<T>` for streaming data with built-in content-type handling for Server-Sent Events, JSON arrays, and NDJSON.
142

143
```java { .api }
144
@Route(path = "/stream", produces = ReactiveRoutes.EVENT_STREAM)
145
public Multi<String> streamEvents() { return Multi.createFrom().items("event1", "event2"); }
146

147
public class ReactiveRoutes {
148
    public static final String APPLICATION_JSON = "application/json";
149
    public static final String EVENT_STREAM = "text/event-stream";
150
    public static final String ND_JSON = "application/x-ndjson";
151
    public static final String JSON_STREAM = "application/stream+json";
152
}
153
```
154

155
[Reactive Streaming](./reactive-streaming.md)
156

157
### Request Filtering
158

159
Cross-cutting concern implementation using `@RouteFilter` annotation for handling authentication, logging, request modification, and other concerns that apply across multiple endpoints.
160

161
```java { .api }
162
@RouteFilter(priority = 10)
163
public void authenticate(RoutingExchange exchange) {
164
    // Filter logic
165
}
166
```
167

168
[Request Filtering](./request-filtering.md)
169

170
## Types
171

172
```java { .api }
173
public enum Route.HttpMethod {
174
    GET, HEAD, POST, PUT, DELETE, OPTIONS
175
}
176

177
public enum Route.HandlerType {
178
    NORMAL, BLOCKING, FAILURE;
179
    public static HandlerType from(String value);
180
}
181

182
public interface ReactiveRoutes.ServerSentEvent<T> {
183
    default String event() { return null; }
184
    T data();
185
    default long id() { return -1L; }
186
}
187
```