0
# HTTP Requests and Responses
1

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

4
## Capabilities
5

6
### HTTP Method Shortcuts
7

8
Convenient methods for common HTTP operations with optional URI parameters.
9

10
```java { .api }
11
/**
12
 * Create a request for a specific HTTP method
13
 * @param method HTTP method
14
 * @return a new request (not thread safe)
15
 */
16
REQ method(Method method);
17

18
/**
19
 * Shortcut for GET method with URI
20
 * @param uri path to resolve against base URI, or full URI
21
 * @return a new request (not thread safe)
22
 */
23
default REQ get(String uri);
24

25
/**
26
 * Shortcut for GET method with default path
27
 * @return a new request (not thread safe)
28
 */
29
default REQ get();
30

31
/**
32
 * Shortcut for POST method with URI
33
 * @param uri path to resolve against base URI, or full URI
34
 * @return a new request (not thread safe)
35
 */
36
default REQ post(String uri);
37

38
/**
39
 * Shortcut for POST method with default path
40
 * @return a new request (not thread safe)
41
 */
42
default REQ post();
43

44
/**
45
 * Shortcut for PUT method with URI
46
 * @param uri path to resolve against base URI, or full URI
47
 * @return a new request (not thread safe)
48
 */
49
default REQ put(String uri);
50

51
/**
52
 * Shortcut for PUT method with default path
53
 * @return a new request (not thread safe)
54
 */
55
default REQ put();
56

57
/**
58
 * Shortcut for DELETE method with URI
59
 * @param uri path to resolve against base URI, or full URI
60
 * @return a new request (not thread safe)
61
 */
62
default REQ delete(String uri);
63

64
/**
65
 * Shortcut for DELETE method with default path
66
 * @return a new request (not thread safe)
67
 */
68
default REQ delete();
69

70
/**
71
 * Shortcut for HEAD method with URI
72
 * @param uri path to resolve against base URI, or full URI
73
 * @return a new request (not thread safe)
74
 */
75
default REQ head(String uri);
76

77
/**
78
 * Shortcut for HEAD method with default path
79
 * @return a new request (not thread safe)
80
 */
81
default REQ head();
82

83
/**
84
 * Shortcut for OPTIONS method with URI
85
 * @param uri path to resolve against base URI, or full URI
86
 * @return a new request (not thread safe)
87
 */
88
default REQ options(String uri);
89

90
/**
91
 * Shortcut for OPTIONS method with default path
92
 * @return a new request (not thread safe)
93
 */
94
default REQ options();
95

96
/**
97
 * Shortcut for TRACE method with URI
98
 * @param uri path to resolve against base URI, or full URI
99
 * @return a new request (not thread safe)
100
 */
101
default REQ trace(String uri);
102

103
/**
104
 * Shortcut for TRACE method with default path
105
 * @return a new request (not thread safe)
106
 */
107
default REQ trace();
108

109
/**
110
 * Shortcut for PATCH method with URI
111
 * @param uri path to resolve against base URI, or full URI
112
 * @return a new request (not thread safe)
113
 */
114
default REQ patch(String uri);
115

116
/**
117
 * Shortcut for PATCH method with default path
118
 * @return a new request (not thread safe)
119
 */
120
default REQ patch();
121
```
122

123
**Usage Examples:**
124

125
```java
126
import io.helidon.webclient.api.WebClient;
127
import io.helidon.http.Method;
128

129
WebClient client = WebClient.create();
130

131
// Using method shortcuts
132
String getResponse = client.get("/api/users").requestEntity(String.class);
133
String postResponse = client.post("/api/users").submit(userData, String.class).entity();
134

135
// Using generic method
136
String patchResponse = client.method(Method.PATCH)
137
    .uri("/api/users/123")
138
    .submit(updateData, String.class)
139
    .entity();
140
```
141

142
### URI Configuration
143

144
Configure the target URI for requests with support for path parameters, query parameters, and fragments.
145

146
```java { .api }
147
/**
148
 * Configure request URI
149
 * @param uri full URI or path to resolve against base URI
150
 * @return request instance
151
 */
152
T uri(String uri);
153

154
/**
155
 * Configure request URI
156
 * @param uri java.net.URI instance
157
 * @return request instance
158
 */
159
T uri(URI uri);
160

161
/**
162
 * Configure request URI
163
 * @param uri ClientUri instance
164
 * @return request instance
165
 */
166
T uri(ClientUri uri);
167

168
/**
169
 * Configure path component (resolves against base URI)
170
 * @param uri path component
171
 * @return request instance
172
 */
173
T path(String uri);
174

175
/**
176
 * Replace path parameters in URI template
177
 * @param name parameter name
178
 * @param value parameter value
179
 * @return request instance
180
 */
181
T pathParam(String name, String value);
182

183
/**
184
 * Add query parameters to the request
185
 * @param name parameter name
186
 * @param values parameter values
187
 * @return request instance
188
 */
189
T queryParam(String name, String... values);
190

191
/**
192
 * Set URI fragment
193
 * @param fragment fragment string
194
 * @return request instance
195
 */
196
T fragment(String fragment);
197

198
/**
199
 * Set URI fragment
200
 * @param fragment UriFragment instance
201
 * @return request instance
202
 */
203
T fragment(UriFragment fragment);
204

205
/**
206
 * Skip URI encoding for this request
207
 * @param skip true to skip encoding
208
 * @return request instance
209
 */
210
T skipUriEncoding(boolean skip);
211
```
212

213
**Usage Examples:**
214

215
```java
216
// Path parameters
217
String response = client.get("/api/users/{id}/posts/{postId}")
218
    .pathParam("id", "123")
219
    .pathParam("postId", "456")
220
    .requestEntity(String.class);
221
// Actual URI: /api/users/123/posts/456
222

223
// Query parameters
224
String response = client.get("/api/search")
225
    .queryParam("q", "java")
226
    .queryParam("type", "code", "docs")
227
    .queryParam("limit", "10")
228
    .requestEntity(String.class);
229
// Actual URI: /api/search?q=java&type=code&type=docs&limit=10
230

231
// Fragment
232
String response = client.get("/api/docs")
233
    .fragment("section-1")
234
    .requestEntity(String.class);
235
// Actual URI: /api/docs#section-1
236
```
237

238
### Header Configuration
239

240
Configure HTTP headers for requests including content negotiation and custom headers.
241

242
```java { .api }
243
/**
244
 * Set a header value
245
 * @param header header instance
246
 * @return request instance
247
 */
248
T header(Header header);
249

250
/**
251
 * Set a header value
252
 * @param name header name
253
 * @param values header values
254
 * @return request instance
255
 */
256
T header(HeaderName name, String... values);
257

258
/**
259
 * Configure multiple headers
260
 * @param headers headers instance
261
 * @return request instance
262
 */
263
T headers(Headers headers);
264

265
/**
266
 * Configure headers using a consumer
267
 * @param headersConsumer consumer to configure headers
268
 * @return request instance
269
 */
270
T headers(Consumer<ClientRequestHeaders> headersConsumer);
271

272
/**
273
 * Set Accept header for content negotiation
274
 * @param accepted accepted media types
275
 * @return request instance
276
 */
277
T accept(HttpMediaType... accepted);
278

279
/**
280
 * Set Accept header for content negotiation
281
 * @param acceptedTypes accepted media types
282
 * @return request instance
283
 */
284
T accept(MediaType... acceptedTypes);
285

286
/**
287
 * Set Content-Type header
288
 * @param contentType content type
289
 * @return request instance
290
 */
291
T contentType(MediaType contentType);
292
```
293

294
**Usage Examples:**
295

296
```java
297
import io.helidon.http.Header;
298
import io.helidon.http.HeaderNames;
299
import io.helidon.http.MediaType;
300

301
String response = client.post("/api/users")
302
    .contentType(MediaType.APPLICATION_JSON)
303
    .accept(MediaType.APPLICATION_JSON)
304
    .header(HeaderNames.AUTHORIZATION, "Bearer " + token)
305
    .header(Header.create("X-Custom-Header", "value"))
306
    .headers(headers -> {
307
        headers.add("X-Request-ID", requestId);
308
        headers.add("X-Client-Version", "1.0");
309
    })
310
    .submit(userData, String.class)
311
    .entity();
312
```
313

314
### Request Execution
315

316
Execute requests with different patterns for handling request bodies and response types.
317

318
```java { .api }
319
/**
320
 * Execute request without entity
321
 * @return HTTP response
322
 */
323
HttpClientResponse request();
324

325
/**
326
 * Submit request with entity
327
 * @param entity request entity
328
 * @return HTTP response
329
 */
330
HttpClientResponse submit(Object entity);
331

332
/**
333
 * Handle output stream for request body
334
 * @param outputStreamConsumer consumer to write to output stream
335
 * @return HTTP response
336
 */
337
HttpClientResponse outputStream(OutputStreamHandler outputStreamConsumer);
338

339
/**
340
 * Execute request without entity and return typed response
341
 * @param type expected response type
342
 * @return typed response wrapper
343
 */
344
<E> ClientResponseTyped<E> request(Class<E> type);
345

346
/**
347
 * Execute request without entity and return entity directly
348
 * Throws exception on non-success status
349
 * @param type expected response type
350
 * @return response entity
351
 */
352
<E> E requestEntity(Class<E> type);
353

354
/**
355
 * Submit request with entity and return typed response
356
 * @param entity request entity
357
 * @param requestedType expected response type
358
 * @return typed response wrapper
359
 */
360
<T> ClientResponseTyped<T> submit(Object entity, Class<T> requestedType);
361
```
362

363
**Usage Examples:**
364

365
```java
366
// Simple request without entity
367
HttpClientResponse response = client.get("/api/users").request();
368
String body = response.as(String.class);
369

370
// Request with automatic entity conversion  
371
String users = client.get("/api/users").requestEntity(String.class);
372

373
// Request with typed response
374
ClientResponseTyped<List<User>> typedResponse = client.get("/api/users")
375
    .request(new GenericType<List<User>>() {});
376
List<User> users = typedResponse.entity();
377

378
// POST with entity
379
User newUser = client.post("/api/users")
380
    .submit(userData, User.class)
381
    .entity();
382

383
// Streaming request body
384
HttpClientResponse response = client.post("/api/upload")
385
    .outputStream(outputStream -> {
386
        // Write data to output stream
387
        outputStream.write(data);
388
    });
389
```
390

391
### Request Configuration
392

393
Configure request-specific settings that override client defaults.
394

395
```java { .api }
396
/**
397
 * Configure TLS for this specific request
398
 * @param tls TLS configuration
399
 * @return request instance
400
 */
401
T tls(Tls tls);
402

403
/**
404
 * Configure proxy for this specific request
405
 * @param proxy proxy configuration
406
 * @return request instance
407
 */
408
T proxy(Proxy proxy);
409

410
/**
411
 * Configure redirect behavior for this request
412
 * @param followRedirects true to follow redirects
413
 * @return request instance
414
 */
415
T followRedirects(boolean followRedirects);
416

417
/**
418
 * Configure maximum redirects for this request
419
 * @param maxRedirects maximum redirect count
420
 * @return request instance
421
 */
422
T maxRedirects(int maxRedirects);
423

424
/**
425
 * Configure read timeout for this request
426
 * @param readTimeout timeout duration
427
 * @return request instance
428
 */
429
T readTimeout(Duration readTimeout);
430

431
/**
432
 * Configure 100-Continue timeout for this request
433
 * @param readContinueTimeout timeout duration
434
 * @return request instance
435
 */
436
T readContinueTimeout(Duration readContinueTimeout);
437

438
/**
439
 * Configure Expect: 100-Continue header
440
 * @param sendExpectContinue true to send header
441
 * @return request instance
442
 */
443
T sendExpectContinue(boolean sendExpectContinue);
444

445
/**
446
 * Configure keep-alive for this request
447
 * @param keepAlive true to enable keep-alive
448
 * @return request instance
449
 */
450
T keepAlive(boolean keepAlive);
451

452
/**
453
 * Use explicit connection for this request
454
 * @param connection connection instance
455
 * @return request instance
456
 */
457
T connection(ClientConnection connection);
458

459
/**
460
 * Add request property for service consumption
461
 * @param propertyName property name
462
 * @param propertyValue property value
463
 * @return request instance
464
 */
465
T property(String propertyName, String propertyValue);
466
```
467

468
### Response Handling
469

470
Access response data, metadata, and typed content conversion.
471

472
```java { .api }
473
/**
474
 * Get response entity for reading
475
 * @return readable entity
476
 */
477
ReadableEntity entity();
478

479
/**
480
 * Get response input stream (shortcut)
481
 * @return response input stream
482
 */
483
default InputStream inputStream();
484

485
/**
486
 * Read entity as specific type (shortcut)
487
 * @param type target type
488
 * @return converted entity
489
 */
490
default <T> T as(Class<T> type);
491

492
/**
493
 * Register source listener for streaming responses
494
 * @param sourceType source type
495
 * @param source source instance
496
 */
497
default <T extends Source<?>> void source(GenericType<T> sourceType, T source);
498

499
/**
500
 * Close response (may not impact connection)
501
 */
502
void close();
503
```
504

505
**Usage Examples:**
506

507
```java
508
// Access response metadata
509
HttpClientResponse response = client.get("/api/users").request();
510
Status status = response.status();
511
ClientResponseHeaders headers = response.headers();
512
Optional<MediaType> contentType = response.contentType();
513
long contentLength = response.contentLength();
514

515
// Read response entity
516
String body = response.as(String.class);
517

518
// Streaming response
519
try (HttpClientResponse response = client.get("/api/large-data").request()) {
520
    try (InputStream inputStream = response.inputStream()) {
521
        // Process stream
522
    }
523
}
524

525
// Typed response
526
ClientResponseTyped<User> typedResponse = client.get("/api/users/123")
527
    .request(User.class);
528
if (typedResponse.status().code() == 200) {
529
    User user = typedResponse.entity();
530
}
531
```
532

533
### Response Base Interface
534

535
Common response functionality available to all response types.
536

537
```java { .api }
538
/**
539
 * Get HTTP status
540
 * @return response status
541
 */
542
Status status();
543

544
/**
545
 * Get response headers
546
 * @return response headers
547
 */
548
ClientResponseHeaders headers();
549

550
/**
551
 * Get Content-Type header
552
 * @return content type if present
553
 */
554
Optional<MediaType> contentType();
555

556
/**
557
 * Get Content-Length header
558
 * @return content length or -1 if not specified
559
 */
560
long contentLength();
561
562
```
563

564
### Protocol-Specific Request Features
565

566
Force specific HTTP protocol version for a request.
567

568
```java { .api }
569
/**
570
 * Force specific HTTP protocol version
571
 * @param protocol protocol identifier (e.g., "http/1.1", "h2")
572
 * @return request instance
573
 */
574
HttpClientRequest protocolId(String protocol);
575
```
576

577
**Usage Examples:**
578

579
```java
580
// Force HTTP/1.1
581
HttpClientResponse response = client.get("/api/data")
582
    .protocolId("http/1.1")
583
    .request();
584

585
// Force HTTP/2
586
HttpClientResponse response = client.get("/api/data")
587
    .protocolId("h2")
588
    .request();
589
```
590

591
## Types
592

593
```java { .api }
594
public interface HttpClientRequest extends ClientRequest<HttpClientRequest> {
595
    HttpClientRequest protocolId(String protocol);
596
}
597

598
public interface ClientRequest<T> {
599
    T uri(String uri);
600
    T uri(URI uri);
601
    T uri(ClientUri uri);
602
    T path(String uri);
603
    T pathParam(String name, String value);
604
    T queryParam(String name, String... values);
605
    T fragment(String fragment);
606
    T fragment(UriFragment fragment);
607
    T header(Header header);
608
    T header(HeaderName name, String... values);
609
    T headers(Headers headers);
610
    T headers(Consumer<ClientRequestHeaders> headersConsumer);
611
    T accept(HttpMediaType... accepted);
612
    T accept(MediaType... acceptedTypes);
613
    T contentType(MediaType contentType);
614
    T tls(Tls tls);
615
    T proxy(Proxy proxy);
616
    T followRedirects(boolean followRedirects);
617
    T maxRedirects(int maxRedirects);
618
    T readTimeout(Duration readTimeout);
619
    T readContinueTimeout(Duration readContinueTimeout);
620
    T sendExpectContinue(boolean sendExpectContinue);
621
    T keepAlive(boolean keepAlive);
622
    T connection(ClientConnection connection);
623
    T skipUriEncoding(boolean skip);
624
    T property(String propertyName, String propertyValue);
625
    
626
    HttpClientResponse request();
627
    HttpClientResponse submit(Object entity);
628
    HttpClientResponse outputStream(OutputStreamHandler outputStreamConsumer);
629
    <E> ClientResponseTyped<E> request(Class<E> type);
630
    <E> E requestEntity(Class<E> type);
631
    <T> ClientResponseTyped<T> submit(Object entity, Class<T> requestedType);
632
}
633

634
public interface HttpClientResponse extends ClientResponseBase, AutoCloseable {
635
    ReadableEntity entity();
636
    default InputStream inputStream();
637
    default <T> T as(Class<T> type);
638
    default <T extends Source<?>> void source(GenericType<T> sourceType, T source);
639
    void close();
640
}
641

642
public interface ClientResponseTyped<E> extends ClientResponseBase {
643
    E entity();
644
}
645

646
public interface ClientResponseBase {
647
    Status status();
648
    ClientResponseHeaders headers();
649
    Optional<MediaType> contentType();
650
    long contentLength();
651
}
652

653
@FunctionalInterface
654
public interface OutputStreamHandler {
655
    void handle(OutputStream outputStream) throws IOException;
656
}
657
```