0
# Request Building
1

2
Fluent API for building HTTP requests with URLs, methods, headers, and request bodies. Requests are immutable once built.
3

4
## Capabilities
5

6
### Request
7

8
Immutable HTTP request with URL, method, headers, and optional body.
9

10
```java { .api }
11
/**
12
 * An HTTP request. Instances of this class are immutable if their body
13
 * is null or itself immutable.
14
 */
15
public final class Request {
16
    public HttpUrl httpUrl();
17
    public URL url();
18
    public URI uri() throws IOException;
19
    public String urlString();
20
    public String method();
21
    public Headers headers();
22
    public String header(String name);
23
    public List<String> headers(String name);
24
    public RequestBody body();
25
    public Object tag();
26
    public Builder newBuilder();
27
    public CacheControl cacheControl();
28
    public boolean isHttps();
29
}
30
```
31

32
### Request.Builder
33

34
Builder for constructing Request objects with fluent API.
35

36
```java { .api }
37
/**
38
 * Builder for constructing Request objects.
39
 */
40
public static class Builder {
41
    public Builder();
42
    public Builder url(HttpUrl url);
43
    public Builder url(String url);
44
    public Builder url(URL url);
45
    public Builder header(String name, String value);
46
    public Builder addHeader(String name, String value);
47
    public Builder removeHeader(String name);
48
    public Builder headers(Headers headers);
49
    public Builder cacheControl(CacheControl cacheControl);
50
    public Builder get();
51
    public Builder head();
52
    public Builder post(RequestBody body);
53
    public Builder delete(RequestBody body);
54
    public Builder delete();
55
    public Builder put(RequestBody body);
56
    public Builder patch(RequestBody body);
57
    public Builder method(String method, RequestBody body);
58
    public Builder tag(Object tag);
59
    public Request build();
60
}
61
```
62

63
**Basic Usage:**
64

65
```java
66
// Simple GET request
67
Request request = new Request.Builder()
68
    .url("https://api.example.com/users")
69
    .build();
70

71
// POST request with JSON body
72
RequestBody body = RequestBody.create(
73
    MediaType.parse("application/json"), 
74
    "{\"name\":\"John\",\"email\":\"john@example.com\"}"
75
);
76
Request request = new Request.Builder()
77
    .url("https://api.example.com/users")
78
    .post(body)
79
    .build();
80
```
81

82
### URL Configuration
83

84
Set the target URL for the HTTP request using various URL types.
85

86
```java { .api }
87
/**
88
 * Sets the URL target of this request.
89
 * @param url the HttpUrl to use
90
 * @return this builder for method chaining
91
 */
92
public Builder url(HttpUrl url);
93

94
/**
95
 * Sets the URL target of this request.
96
 * @param url the URL string to parse and use
97
 * @return this builder for method chaining
98
 * @throws IllegalArgumentException if url is not a valid HTTP or HTTPS URL
99
 */
100
public Builder url(String url);
101

102
/**
103
 * Sets the URL target of this request.
104
 * @param url the java.net.URL to convert and use
105
 * @return this builder for method chaining
106
 * @throws IllegalArgumentException if the scheme is not http or https
107
 */
108
public Builder url(URL url);
109
```
110

111
**Usage Examples:**
112

113
```java
114
// From string
115
Request request = new Request.Builder()
116
    .url("https://api.example.com/users?page=1")
117
    .build();
118

119
// From HttpUrl (with building)
120
HttpUrl url = HttpUrl.parse("https://api.example.com")
121
    .newBuilder()
122
    .addPathSegment("users")
123
    .addQueryParameter("page", "1")
124
    .build();
125
Request request = new Request.Builder()
126
    .url(url)
127
    .build();
128

129
// From java.net.URL
130
URL javaUrl = new URL("https://api.example.com/users");
131
Request request = new Request.Builder()
132
    .url(javaUrl)
133
    .build();
134
```
135

136
### Header Management
137

138
Add, set, and remove HTTP headers for the request.
139

140
```java { .api }
141
/**
142
 * Sets the header named name to value. If this request already has any 
143
 * headers with that name, they are all replaced.
144
 * @param name the header name
145
 * @param value the header value
146
 * @return this builder for method chaining
147
 */
148
public Builder header(String name, String value);
149

150
/**
151
 * Adds a header with name and value. Prefer this method for multiply-valued 
152
 * headers like "Cookie".
153
 * @param name the header name
154
 * @param value the header value
155
 * @return this builder for method chaining
156
 */
157
public Builder addHeader(String name, String value);
158

159
/**
160
 * Removes all headers with the specified name.
161
 * @param name the header name to remove
162
 * @return this builder for method chaining
163
 */
164
public Builder removeHeader(String name);
165

166
/**
167
 * Removes all headers on this builder and adds headers.
168
 * @param headers the headers to set
169
 * @return this builder for method chaining
170
 */
171
public Builder headers(Headers headers);
172
```
173

174
**Usage Examples:**
175

176
```java
177
Request request = new Request.Builder()
178
    .url("https://api.example.com/users")
179
    .header("Authorization", "Bearer token123")
180
    .header("Content-Type", "application/json")
181
    .addHeader("Accept", "application/json")
182
    .addHeader("Accept", "text/plain") // Multiple values
183
    .build();
184

185
// Using Headers object
186
Headers headers = new Headers.Builder()
187
    .add("User-Agent", "MyApp/1.0")
188
    .add("Accept-Language", "en-US")
189
    .build();
190
Request request = new Request.Builder()
191
    .url("https://api.example.com/users")
192
    .headers(headers)
193
    .build();
194
```
195

196
### Cache Control
197

198
Configure caching directives for the request.
199

200
```java { .api }
201
/**
202
 * Sets this request's Cache-Control header, replacing any cache control 
203
 * headers already present.
204
 * @param cacheControl the cache control directives
205
 * @return this builder for method chaining
206
 */
207
public Builder cacheControl(CacheControl cacheControl);
208
```
209

210
**Usage Examples:**
211

212
```java
213
// Force network request (bypass cache)
214
Request request = new Request.Builder()
215
    .url("https://api.example.com/users")
216
    .cacheControl(CacheControl.FORCE_NETWORK)
217
    .build();
218

219
// Use cache only
220
Request request = new Request.Builder()
221
    .url("https://api.example.com/users")
222
    .cacheControl(CacheControl.FORCE_CACHE)
223
    .build();
224

225
// Custom cache control
226
CacheControl cacheControl = new CacheControl.Builder()
227
    .maxAge(60, TimeUnit.SECONDS)
228
    .noCache()
229
    .build();
230
Request request = new Request.Builder()
231
    .url("https://api.example.com/users")
232
    .cacheControl(cacheControl)
233
    .build();
234
```
235

236
### HTTP Methods
237

238
Set the HTTP method and optional request body.
239

240
```java { .api }
241
/**
242
 * Sets the request method to GET and removes any request body.
243
 * @return this builder for method chaining
244
 */
245
public Builder get();
246

247
/**
248
 * Sets the request method to HEAD and removes any request body.
249
 * @return this builder for method chaining
250
 */
251
public Builder head();
252

253
/**
254
 * Sets the request method to POST with the specified body.
255
 * @param body the request body
256
 * @return this builder for method chaining
257
 */
258
public Builder post(RequestBody body);
259

260
/**
261
 * Sets the request method to DELETE with the specified body.
262
 * @param body the request body
263
 * @return this builder for method chaining
264
 */
265
public Builder delete(RequestBody body);
266

267
/**
268
 * Sets the request method to DELETE with an empty body.
269
 * @return this builder for method chaining
270
 */
271
public Builder delete();
272

273
/**
274
 * Sets the request method to PUT with the specified body.
275
 * @param body the request body
276
 * @return this builder for method chaining
277
 */
278
public Builder put(RequestBody body);
279

280
/**
281
 * Sets the request method to PATCH with the specified body.
282
 * @param body the request body
283
 * @return this builder for method chaining
284
 */
285
public Builder patch(RequestBody body);
286

287
/**
288
 * Sets the request method and body.
289
 * @param method the HTTP method
290
 * @param body the request body (may be null for methods that don't require a body)
291
 * @return this builder for method chaining
292
 */
293
public Builder method(String method, RequestBody body);
294
```
295

296
**Usage Examples:**
297

298
```java
299
// GET request
300
Request getRequest = new Request.Builder()
301
    .url("https://api.example.com/users")
302
    .get()
303
    .build();
304

305
// POST request with JSON
306
RequestBody jsonBody = RequestBody.create(
307
    MediaType.parse("application/json"),
308
    "{\"name\":\"John\",\"email\":\"john@example.com\"}"
309
);
310
Request postRequest = new Request.Builder()
311
    .url("https://api.example.com/users")
312
    .post(jsonBody)
313
    .build();
314

315
// PUT request
316
RequestBody putBody = RequestBody.create(
317
    MediaType.parse("application/json"),
318
    "{\"id\":1,\"name\":\"John Updated\"}"
319
);
320
Request putRequest = new Request.Builder()
321
    .url("https://api.example.com/users/1")
322
    .put(putBody)
323
    .build();
324

325
// DELETE request
326
Request deleteRequest = new Request.Builder()
327
    .url("https://api.example.com/users/1")
328
    .delete()
329
    .build();
330

331
// Custom method
332
Request customRequest = new Request.Builder()
333
    .url("https://api.example.com/users")
334
    .method("OPTIONS", null)
335
    .build();
336
```
337

338
### Request Tagging
339

340
Attach tags to requests for identification and cancellation.
341

342
```java { .api }
343
/**
344
 * Attaches tag to the request. It can be used later to cancel the request.
345
 * If the tag is unspecified or null, the request is canceled by using the 
346
 * request itself as the tag.
347
 * @param tag the tag to attach
348
 * @return this builder for method chaining
349
 */
350
public Builder tag(Object tag);
351
```
352

353
**Usage Examples:**
354

355
```java
356
// Tag request for later cancellation
357
String requestTag = "user-profile-request";
358
Request request = new Request.Builder()
359
    .url("https://api.example.com/users/1")
360
    .tag(requestTag)
361
    .build();
362

363
// Cancel requests with this tag later
364
client.cancel(requestTag);
365

366
// Tag with custom object
367
class RequestContext {
368
    String userId;
369
    String operation;
370
}
371
RequestContext context = new RequestContext();
372
context.userId = "123";
373
context.operation = "fetch-profile";
374

375
Request request = new Request.Builder()
376
    .url("https://api.example.com/users/123")
377
    .tag(context)
378
    .build();
379
```
380

381
### Building the Request
382

383
Create the final immutable Request object.
384

385
```java { .api }
386
/**
387
 * Creates the Request with the configured parameters.
388
 * @return the built Request
389
 * @throws IllegalStateException if url is null
390
 */
391
public Request build();
392
```
393

394
### Request Properties
395

396
Access properties of the built Request object.
397

398
```java { .api }
399
/**
400
 * Returns the HttpUrl representation of the request URL.
401
 * @return the HttpUrl
402
 */
403
public HttpUrl httpUrl();
404

405
/**
406
 * Returns the java.net.URL representation of the request URL.
407
 * @return the URL
408
 */
409
public URL url();
410

411
/**
412
 * Returns the java.net.URI representation of the request URL.
413
 * @return the URI
414
 * @throws IOException if URI construction fails
415
 */
416
public URI uri() throws IOException;
417

418
/**
419
 * Returns the URL as a string.
420
 * @return the URL string
421
 */
422
public String urlString();
423

424
/**
425
 * Returns the HTTP method (GET, POST, etc.).
426
 * @return the HTTP method
427
 */
428
public String method();
429

430
/**
431
 * Returns the request headers.
432
 * @return the Headers object
433
 */
434
public Headers headers();
435

436
/**
437
 * Returns the value of the specified header, or null if not present.
438
 * @param name the header name
439
 * @return the header value or null
440
 */
441
public String header(String name);
442

443
/**
444
 * Returns all values for the specified header name.
445
 * @param name the header name
446
 * @return list of header values
447
 */
448
public List<String> headers(String name);
449

450
/**
451
 * Returns the request body, or null if this request doesn't have a body.
452
 * @return the request body or null
453
 */
454
public RequestBody body();
455

456
/**
457
 * Returns the tag attached to this request, or the request itself if no tag was set.
458
 * @return the tag object
459
 */
460
public Object tag();
461

462
/**
463
 * Returns true if this request uses HTTPS.
464
 * @return true if HTTPS, false if HTTP
465
 */
466
public boolean isHttps();
467

468
/**
469
 * Returns the cache control directives for this request.
470
 * @return the CacheControl object
471
 */
472
public CacheControl cacheControl();
473
```
474

475
### Creating Builder from Existing Request
476

477
Modify existing requests by creating new builders.
478

479
```java { .api }
480
/**
481
 * Returns a new Builder based on this request.
482
 * @return a new Builder with this request's configuration
483
 */
484
public Builder newBuilder();
485
```
486

487
**Usage Examples:**
488

489
```java
490
// Create base request
491
Request baseRequest = new Request.Builder()
492
    .url("https://api.example.com/users")
493
    .header("User-Agent", "MyApp/1.0")
494
    .build();
495

496
// Create modified request
497
Request modifiedRequest = baseRequest.newBuilder()
498
    .addHeader("Authorization", "Bearer token123")
499
    .build();
500

501
// Change method while keeping other properties
502
Request postRequest = baseRequest.newBuilder()
503
    .post(RequestBody.create(MediaType.parse("application/json"), "{}"))
504
    .build();
505
```