0
# Helidon WebClient
1

2
Helidon WebClient is a comprehensive HTTP client library designed for Java microservices, providing flexible HTTP communication with support for multiple HTTP protocol versions (HTTP/1.1, HTTP/2), automatic version negotiation through ALPN, DNS resolution customization, proxy support, and built-in observability features. Built on Java 21 Virtual Threads, it delivers high throughput while supporting both blocking and reactive programming models.
3

4
## Package Information
5

6
- **Package Name**: helidon-webclient
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to your Maven dependencies:
10

11
```xml
12
<dependency>
13
    <groupId>io.helidon.webclient</groupId>
14
    <artifactId>helidon-webclient</artifactId>
15
    <version>4.2.2</version>
16
</dependency>
17
```
18

19
## Core Imports
20

21
```java
22
import io.helidon.webclient.api.WebClient;
23
import io.helidon.webclient.api.HttpClient;
24
import io.helidon.webclient.api.HttpClientRequest;
25
import io.helidon.webclient.api.HttpClientResponse;
26
import io.helidon.webclient.api.WebClientConfig;
27
import io.helidon.webclient.api.ClientUri;
28
import io.helidon.webclient.api.Proxy;
29
import io.helidon.webclient.api.WebClientCookieManager;
30
import io.helidon.http.MediaType;
31
import java.time.Duration;
32
import java.util.function.Consumer;
33
```
34

35
## Basic Usage
36

37
```java
38
import io.helidon.webclient.api.WebClient;
39

40
// Create default client
41
WebClient client = WebClient.create();
42

43
// Simple GET request
44
String response = client.get("https://api.example.com/data")
45
    .requestEntity(String.class);
46

47
// POST request with JSON entity
48
MyResponse result = client.post("https://api.example.com/submit")
49
    .contentType(MediaType.APPLICATION_JSON)
50
    .submit(requestData, MyResponse.class)
51
    .entity();
52

53
// Configure client with custom settings
54
WebClient configuredClient = WebClient.builder()
55
    .baseUri("https://api.example.com")
56
    .addHeader("Authorization", "Bearer token")
57
    .readTimeout(Duration.ofSeconds(30))
58
    .followRedirects(true)
59
    .build();
60
```
61

62
## Architecture
63

64
Helidon WebClient is designed around several key architectural components:
65

66
- **Multi-Protocol Support**: Automatically selects HTTP/1.1 or HTTP/2 based on server capabilities and configuration
67
- **Protocol Negotiation**: Uses ALPN (Application-Layer Protocol Negotiation) for TLS connections and HTTP upgrade mechanisms for plaintext
68
- **Virtual Thread Integration**: Built on Java 21 Virtual Threads for high-throughput, non-blocking operations
69
- **Service Chain Architecture**: Extensible interceptor pattern for adding cross-cutting concerns like authentication, logging, and metrics
70
- **Connection Management**: Intelligent connection pooling and caching with configurable strategies
71
- **DNS Resolution**: Pluggable DNS resolution with multiple strategies (default, first-available, round-robin)
72

73
## Capabilities
74

75
### Client Creation and Configuration
76

77
Core functionality for creating and configuring WebClient instances with various settings including base URIs, default headers, timeouts, and protocol preferences.
78

79
```java { .api }
80
public interface WebClient extends HttpClient<HttpClientRequest> {
81
    static WebClient create();
82
    static WebClient create(WebClientConfig config);
83
    static WebClient create(Consumer<WebClientConfig.Builder> consumer);
84
    static WebClientConfig.Builder builder();
85
}
86
```
87

88
[Client Creation and Configuration](./client-configuration.md)
89

90
### HTTP Requests and Responses
91

92
Fluent API for building and executing HTTP requests with support for all HTTP methods, headers, query parameters, request bodies, and typed response handling.
93

94
```java { .api }
95
public interface HttpClient<REQ extends ClientRequest<REQ>> {
96
    REQ method(Method method);
97
    default REQ get(String uri);
98
    default REQ post(String uri);
99
    default REQ put(String uri);
100
    default REQ delete(String uri);
101
}
102

103
public interface ClientRequest<T> {
104
    T uri(String uri);
105
    T header(HeaderName name, String... values);
106
    T queryParam(String name, String... values);
107
    T contentType(MediaType contentType);
108
    HttpClientResponse request();
109
    HttpClientResponse submit(Object entity);
110
    <E> E requestEntity(Class<E> type);
111
}
112
```
113

114
[HTTP Requests and Responses](./requests-responses.md)
115

116
### Protocol-Specific Clients
117

118
Access to protocol-specific functionality including HTTP/1.1 features like protocol upgrades, HTTP/2 specific capabilities, and non-HTTP protocols like WebSocket and gRPC.
119

120
```java { .api }
121
public interface WebClient {
122
    <T, C extends ProtocolConfig> T client(Protocol<T, C> protocol);
123
    <T, C extends ProtocolConfig> T client(Protocol<T, C> protocol, C protocolConfig);
124
}
125
```
126

127
[Protocol-Specific Clients](./protocol-clients.md)
128

129
### Connection Management
130

131
Advanced connection handling including custom connections, connection caching, proxy support, TLS configuration, and DNS resolution strategies.
132

133
```java { .api }
134
public interface ClientConnection extends ReleasableResource {
135
    DataReader reader();
136
    DataWriter writer();
137
    String channelId();
138
    HelidonSocket helidonSocket();
139
    void readTimeout(Duration readTimeout);
140
}
141

142
public interface DnsAddressLookup {
143
    List<InetAddress> listAddresses(String hostname);
144
    static DnsAddressLookup defaultLookup();
145
    static DnsAddressLookup roundRobin();
146
}
147
```
148

149
[Connection Management](./connection-management.md)
150

151
### Service Integration
152

153
Client-side interceptors and middleware for adding cross-cutting concerns like authentication, logging, metrics, tracing, and custom request/response processing.
154

155
```java { .api }
156
@FunctionalInterface
157
public interface WebClientService extends NamedService {
158
    WebClientServiceResponse handle(Chain chain, WebClientServiceRequest clientRequest);
159
    
160
    interface Chain {
161
        WebClientServiceResponse proceed(WebClientServiceRequest clientRequest);
162
    }
163
}
164
```
165

166
[Service Integration](./service-integration.md)
167

168
## Types
169

170
```java { .api }
171
public interface WebClientConfig extends HttpClientConfig {
172
    List<ProtocolConfig> protocolConfigs();
173
    List<String> protocolPreference();
174
}
175

176
public interface HttpClientConfig {
177
    Optional<ClientUri> baseUri();
178
    Duration readTimeout();
179
    boolean followRedirects();
180
    int maxRedirects();
181
    Optional<Proxy> proxy();
182
    SocketOptions socketOptions();
183
    DnsResolver dnsResolver();
184
    ExecutorService executor();
185
    List<WebClientService> services();
186
    Optional<WebClientCookieManager> cookieManager();
187
}
188

189
public class ClientUri implements UriInfo {
190
    static ClientUri create();
191
    static ClientUri create(URI baseUri);
192
    ClientUri scheme(String scheme);
193
    ClientUri host(String host);
194
    ClientUri port(int port);
195
    ClientUri path(String path);
196
    ClientUri queryParam(String name, String... values);
197
    URI toUri();
198
}
199

200
public class Proxy {
201
    static Builder builder();
202
    static Proxy noProxy();
203
    static Proxy create();
204
    ProxyType type();
205
    String host();
206
    int port();
207
    
208
    enum ProxyType { NONE, SYSTEM, HTTP }
209
}
210

211
public interface HttpClientResponse extends ClientResponseBase, AutoCloseable {
212
    ReadableEntity entity();
213
    default InputStream inputStream();
214
    default <T> T as(Class<T> type);
215
}
216

217
public interface ClientResponseBase {
218
    Status status();
219
    ClientResponseHeaders headers();
220
    Optional<MediaType> contentType();
221
    long contentLength();
222
}
223

224
public class WebClientCookieManager extends CookieManager {
225
    static WebClientCookieManager create(WebClientCookieManagerConfig config);
226
    static WebClientCookieManager create(Consumer<WebClientCookieManagerConfig.Builder> configConsumer);
227
    static WebClientCookieManagerConfig.Builder builder();
228
    
229
    void request(ClientUri uri, ClientRequestHeaders requestHeaders);
230
    void response(ClientUri uri, ClientResponseHeaders headers);
231
}
232

233
public interface WebClientCookieManagerConfig {
234
    boolean automaticStoreEnabled();
235
    CookiePolicy cookiePolicy();
236
    Map<String, String> defaultCookies();
237
    Optional<CookieStore> cookieStore();
238
}
239
```