0
# Request Building
1

2
Fluent API for constructing HTTP requests with comprehensive support for headers, parameters, body content, authentication, and configuration options using the specification pattern.
3

4
## Capabilities
5

6
### Request Entry Points
7

8
Entry points for building HTTP requests using the fluent specification pattern.
9

10
```java { .api }
11
/**
12
 * Start building the request specification (same as with())
13
 * @return A request specification for fluent configuration
14
 */
15
static RequestSpecification given();
16

17
/**
18
 * Start building the request specification (same as given()) 
19
 * @return A request specification for fluent configuration 
20
 */
21
static RequestSpecification with();
22

23
/**
24
 * Start building DSL expression for immediate request sending
25
 * @return A request sender interface
26
 */
27
static RequestSender when();
28

29
/**
30
 * Create request specification from existing specifications
31
 * @param requestSpecification Pre-configured request specification
32
 * @param responseSpecification Pre-configured response specification
33
 * @return Request sender with both specifications applied
34
 */
35
static RequestSender given(RequestSpecification requestSpecification, ResponseSpecification responseSpecification);
36

37
/**
38
 * Create request specification from existing request specification only
39
 * @param requestSpecification Pre-configured request specification
40
 * @return Request specification with existing spec applied
41
 */
42
static RequestSpecification given(RequestSpecification requestSpecification);
43
```
44

45
**Usage Examples:**
46

47
```java
48
// Basic fluent API
49
given()
50
    .header("Accept", "application/json")
51
    .queryParam("limit", 10)
52
.when()
53
    .get("/users")
54
.then()
55
    .statusCode(200);
56

57
// Immediate request (no additional parameters)
58
when()
59
    .get("/health")
60
.then()
61
    .statusCode(200);
62

63
// Using pre-built specifications
64
RequestSpecification baseSpec = new RequestSpecBuilder()
65
    .setBaseUri("https://api.example.com")
66
    .setContentType(ContentType.JSON)
67
    .build();
68

69
given(baseSpec)
70
    .queryParam("filter", "active")
71
.when()
72
    .get("/users");
73
```
74

75
### Request Body Configuration
76

77
Methods for setting request body content in various formats.
78

79
```java { .api }
80
interface RequestSpecification {
81
    /**
82
     * Set request body as string
83
     * @param body The string body content
84
     * @return Updated request specification
85
     */
86
    RequestSpecification body(String body);
87
    
88
    /**
89
     * Set request body as byte array
90
     * @param body The byte array body content
91
     * @return Updated request specification
92
     */
93
    RequestSpecification body(byte[] body);
94
    
95
    /**
96
     * Set request body from file
97
     * @param file The file to read body content from
98
     * @return Updated request specification
99
     */
100
    RequestSpecification body(File file);
101
    
102
    /**
103
     * Set request body from input stream
104
     * @param stream The input stream to read body content from
105
     * @return Updated request specification
106
     */
107
    RequestSpecification body(InputStream stream);
108
    
109
    /**
110
     * Set request body from Java object (will be serialized to JSON/XML)
111
     * @param object The object to serialize as request body
112
     * @return Updated request specification
113
     */
114
    RequestSpecification body(Object object);
115
    
116
    /**
117
     * Set request body from object with specific object mapper
118
     * @param object The object to serialize
119
     * @param mapper The object mapper to use for serialization
120
     * @return Updated request specification
121
     */
122
    RequestSpecification body(Object object, ObjectMapper mapper);
123
    
124
    /**
125
     * Set request body from object with specific object mapper type
126
     * @param object The object to serialize
127
     * @param mapperType The type of object mapper to use
128
     * @return Updated request specification
129
     */
130
    RequestSpecification body(Object object, ObjectMapperType mapperType);
131
}
132
```
133

134
**Usage Examples:**
135

136
```java
137
// String body
138
given()
139
    .body("{\"name\":\"John\",\"email\":\"john@example.com\"}")
140
    .contentType(ContentType.JSON)
141
.when()
142
    .post("/users");
143

144
// Object body (auto-serialized to JSON)
145
User user = new User("John", "john@example.com");
146
given()
147
    .body(user)
148
    .contentType(ContentType.JSON)
149
.when()
150
    .post("/users");
151

152
// File body
153
given()
154
    .body(new File("user-data.json"))
155
    .contentType(ContentType.JSON)
156
.when()
157
    .post("/users");
158
```
159

160
### Parameter Configuration
161

162
Methods for setting various types of HTTP parameters.
163

164
```java { .api }
165
interface RequestSpecification {
166
    /**
167
     * Add a request parameter (query param for GET, form param for POST)
168
     * @param parameterName The parameter name
169
     * @param parameterValues The parameter values
170
     * @return Updated request specification
171
     */
172
    RequestSpecification param(String parameterName, Object... parameterValues);
173
    
174
    /**
175
     * Add multiple request parameters
176
     * @param parametersMap Map of parameter names to values
177
     * @return Updated request specification
178
     */
179
    RequestSpecification params(Map<String, ?> parametersMap);
180
    
181
    /**
182
     * Add a query parameter
183
     * @param parameterName The query parameter name
184
     * @param parameterValues The query parameter values
185
     * @return Updated request specification
186
     */
187
    RequestSpecification queryParam(String parameterName, Object... parameterValues);
188
    
189
    /**
190
     * Add multiple query parameters
191
     * @param parametersMap Map of query parameter names to values
192
     * @return Updated request specification
193
     */
194
    RequestSpecification queryParams(Map<String, ?> parametersMap);
195
    
196
    /**
197
     * Add a form parameter
198
     * @param parameterName The form parameter name
199
     * @param parameterValues The form parameter values
200
     * @return Updated request specification
201
     */
202
    RequestSpecification formParam(String parameterName, Object... parameterValues);
203
    
204
    /**
205
     * Add multiple form parameters
206
     * @param parametersMap Map of form parameter names to values
207
     * @return Updated request specification
208
     */
209
    RequestSpecification formParams(Map<String, ?> parametersMap);
210
    
211
    /**
212
     * Add a path parameter for URL template substitution
213
     * @param parameterName The path parameter name
214
     * @param parameterValue The path parameter value
215
     * @return Updated request specification
216
     */
217
    RequestSpecification pathParam(String parameterName, Object parameterValue);
218
    
219
    /**
220
     * Add multiple path parameters for URL template substitution
221
     * @param parametersMap Map of path parameter names to values
222
     * @return Updated request specification
223
     */
224
    RequestSpecification pathParams(Map<String, Object> parametersMap);
225
}
226
```
227

228
**Usage Examples:**
229

230
```java
231
// Query parameters
232
given()
233
    .queryParam("page", 1)
234
    .queryParam("size", 20)
235
    .queryParam("sort", "name", "asc")
236
.when()
237
    .get("/users");
238

239
// Form parameters
240
given()
241
    .formParam("username", "john")
242
    .formParam("password", "secret")
243
.when()
244
    .post("/login");
245

246
// Path parameters
247
given()
248
    .pathParam("userId", 123)
249
    .pathParam("postId", 456)
250
.when()
251
    .get("/users/{userId}/posts/{postId}");
252

253
// Multiple parameters with map
254
Map<String, Object> queryParams = new HashMap<>();
255
queryParams.put("status", "active");
256
queryParams.put("role", "admin");
257
given()
258
    .queryParams(queryParams)
259
.when()
260
    .get("/users");
261
```
262

263
### Header Configuration
264

265
Methods for setting HTTP headers.
266

267
```java { .api }
268
interface RequestSpecification {
269
    /**
270
     * Add a header to the request
271
     * @param headerName The header name
272
     * @param headerValue The header value
273
     * @return Updated request specification
274
     */
275
    RequestSpecification header(String headerName, Object headerValue);
276
    
277
    /**
278
     * Add multiple headers to the request
279
     * @param firstHeaderName First header name
280
     * @param firstHeaderValue First header value  
281
     * @param headerNameValuePairs Additional header name-value pairs
282
     * @return Updated request specification
283
     */
284
    RequestSpecification headers(String firstHeaderName, Object firstHeaderValue, Object... headerNameValuePairs);
285
    
286
    /**
287
     * Add headers from a map
288
     * @param headers Map of header names to values
289
     * @return Updated request specification
290
     */
291
    RequestSpecification headers(Map<String, ?> headers);
292
    
293
    /**
294
     * Add headers from Headers object
295
     * @param headers Headers object containing multiple headers
296
     * @return Updated request specification
297
     */
298
    RequestSpecification headers(Headers headers);
299
}
300
```
301

302
**Usage Examples:**
303

304
```java
305
// Single header
306
given()
307
    .header("Accept", "application/json")
308
    .header("Authorization", "Bearer token123")
309
.when()
310
    .get("/protected");
311

312
// Multiple headers
313
given()
314
    .headers("Accept", "application/json", 
315
             "User-Agent", "REST-Assured/5.5.2",
316
             "X-API-Version", "v1")
317
.when()
318
    .get("/api/data");
319

320
// Headers from map
321
Map<String, String> headers = new HashMap<>();
322
headers.put("Accept", "application/json");
323
headers.put("Content-Type", "application/json");
324
given()
325
    .headers(headers)
326
.when()
327
    .post("/api/data");
328
```
329

330
### Cookie Configuration
331

332
Methods for setting HTTP cookies.
333

334
```java { .api }
335
interface RequestSpecification {
336
    /**
337
     * Add a cookie to the request
338
     * @param cookieName The cookie name
339
     * @param cookieValue The cookie value
340
     * @return Updated request specification
341
     */
342
    RequestSpecification cookie(String cookieName, Object cookieValue);
343
    
344
    /**
345
     * Add a detailed cookie to the request
346
     * @param cookie Cookie object with full cookie attributes
347
     * @return Updated request specification
348
     */
349
    RequestSpecification cookie(Cookie cookie);
350
    
351
    /**
352
     * Add multiple cookies to the request
353
     * @param firstCookieName First cookie name
354
     * @param firstCookieValue First cookie value
355
     * @param cookieNameValuePairs Additional cookie name-value pairs
356
     * @return Updated request specification
357
     */
358
    RequestSpecification cookies(String firstCookieName, Object firstCookieValue, Object... cookieNameValuePairs);
359
    
360
    /**
361
     * Add cookies from a map
362
     * @param cookies Map of cookie names to values
363
     * @return Updated request specification
364
     */
365
    RequestSpecification cookies(Map<String, ?> cookies);
366
    
367
    /**
368
     * Add cookies from Cookies object
369
     * @param cookies Cookies object containing multiple cookies
370
     * @return Updated request specification
371
     */
372
    RequestSpecification cookies(Cookies cookies);
373
}
374
```
375

376
### Content Type and Accept Headers
377

378
Methods for setting content type and accept headers.
379

380
```java { .api }
381
interface RequestSpecification {
382
    /**
383
     * Set the content type header
384
     * @param contentType The content type to set
385
     * @return Updated request specification
386
     */
387
    RequestSpecification contentType(ContentType contentType);
388
    
389
    /**
390
     * Set the content type header as string
391
     * @param contentType The content type string
392
     * @return Updated request specification
393
     */
394
    RequestSpecification contentType(String contentType);
395
    
396
    /**
397
     * Set the accept header
398
     * @param mediaTypes The media types to accept
399
     * @return Updated request specification
400
     */
401
    RequestSpecification accept(ContentType mediaTypes);
402
    
403
    /**
404
     * Set the accept header as string
405
     * @param mediaTypes The media types to accept as string
406
     * @return Updated request specification
407
     */
408
    RequestSpecification accept(String mediaTypes);
409
}
410
```
411

412
### Authentication Configuration
413

414
Methods for configuring authentication.
415

416
```java { .api }
417
interface RequestSpecification {
418
    /**
419
     * Access authentication specification
420
     * @return Authentication specification for configuring auth
421
     */
422
    AuthenticationSpecification auth();
423
}
424

425
interface AuthenticationSpecification {
426
    /**
427
     * Use HTTP basic authentication
428
     * @param userName The username
429
     * @param password The password
430
     * @return Updated request specification
431
     */
432
    RequestSpecification basic(String userName, String password);
433
    
434
    /**
435
     * Use preemptive HTTP basic authentication
436
     * @return Preemptive auth specification
437
     */
438
    PreemptiveAuthSpec preemptive();
439
    
440
    /**
441
     * Use HTTP digest authentication
442
     * @param userName The username
443
     * @param password The password
444
     * @return Updated request specification
445
     */
446
    RequestSpecification digest(String userName, String password);
447
    
448
    /**
449
     * Use form-based authentication
450
     * @param userName The username
451
     * @param password The password
452
     * @return Updated request specification
453
     */
454
    RequestSpecification form(String userName, String password);
455
    
456
    /**
457
     * Use OAuth 1.0 authentication
458
     * @param consumerKey OAuth consumer key
459
     * @param consumerSecret OAuth consumer secret
460
     * @param accessToken OAuth access token
461
     * @param secretToken OAuth secret token
462
     * @return Updated request specification
463
     */
464
    RequestSpecification oauth(String consumerKey, String consumerSecret, String accessToken, String secretToken);
465
    
466
    /**
467
     * Use OAuth 2.0 authentication
468
     * @param accessToken OAuth 2.0 access token
469
     * @return Updated request specification
470
     */
471
    RequestSpecification oauth2(String accessToken);
472
    
473
    /**
474
     * Use certificate-based authentication
475
     * @param certURL Path to certificate
476
     * @param password Certificate password
477
     * @return Updated request specification
478
     */
479
    RequestSpecification certificate(String certURL, String password);
480
    
481
    /**
482
     * Disable authentication for this request
483
     * @return Updated request specification
484
     */
485
    RequestSpecification none();
486
}
487
```
488

489
### Multipart Request Configuration
490

491
Methods for configuring multipart/form-data requests.
492

493
```java { .api }
494
interface RequestSpecification {
495
    /**
496
     * Add a multipart form data part
497
     * @param controlName The form control name
498
     * @param filename The filename
499
     * @param data The file data
500
     * @param mimeType The MIME type of the data
501
     * @return Updated request specification
502
     */
503
    RequestSpecification multiPart(String controlName, String filename, byte[] data, String mimeType);
504
    
505
    /**
506
     * Add a multipart form data part from file
507
     * @param controlName The form control name
508
     * @param file The file to upload
509
     * @return Updated request specification
510
     */
511
    RequestSpecification multiPart(String controlName, File file);
512
    
513
    /**
514
     * Add a multipart form data part from file with MIME type
515
     * @param controlName The form control name
516
     * @param file The file to upload
517
     * @param mimeType The MIME type of the file
518
     * @return Updated request specification
519
     */
520
    RequestSpecification multiPart(String controlName, File file, String mimeType);
521
    
522
    /**
523
     * Add a multipart form data specification
524
     * @param multiPartSpecification The multipart specification
525
     * @return Updated request specification
526
     */
527
    RequestSpecification multiPart(MultiPartSpecification multiPartSpecification);
528
}
529
```
530

531
### Configuration and Filters
532

533
Methods for applying configuration and filters.
534

535
```java { .api }
536
interface RequestSpecification {
537
    /**
538
     * Apply configuration to this request
539
     * @param config The REST Assured configuration
540
     * @return Updated request specification
541
     */
542
    RequestSpecification config(RestAssuredConfig config);
543
    
544
    /**
545
     * Apply a specification to this request
546
     * @param requestSpecificationToMerge The specification to merge
547
     * @return Updated request specification
548
     */
549
    RequestSpecification spec(RequestSpecification requestSpecificationToMerge);
550
    
551
    /**
552
     * Add a filter to this request
553
     * @param filter The filter to add
554
     * @return Updated request specification
555
     */
556
    RequestSpecification filter(Filter filter);
557
    
558
    /**
559
     * Add multiple filters to this request
560
     * @param filters The filters to add
561
     * @return Updated request specification  
562
     */
563
    RequestSpecification filters(List<Filter> filters);
564
    
565
    /**
566
     * Add filters to this request
567
     * @param filter The first filter
568
     * @param additionalFilters Additional filters
569
     * @return Updated request specification
570
     */
571
    RequestSpecification filters(Filter filter, Filter... additionalFilters);
572
}
573
```
574

575
## Types
576

577
```java { .api }
578
// Main request specification interface
579
interface RequestSpecification extends RequestSender, RequestSenderOptions {
580
    // All methods listed above are part of this interface
581
}
582

583
// Request sender interface for HTTP method execution
584
interface RequestSender {
585
    Response get(String path, Object... pathParameters);
586
    Response post(String path, Object... pathParameters);
587
    Response put(String path, Object... pathParameters);
588
    Response delete(String path, Object... pathParameters);
589
    Response head(String path, Object... pathParameters);
590
    Response patch(String path, Object... pathParameters);
591
    Response options(String path, Object... pathParameters);
592
    Response request(Method method, String path, Object... pathParameters);
593
    Response request(String method, String path, Object... pathParameters);
594
}
595

596
// Content type enumeration
597
enum ContentType {
598
    JSON("application/json"),
599
    XML("application/xml"),
600
    HTML("text/html"),
601
    TEXT("text/plain"),
602
    URLENC("application/x-www-form-urlencoded"),
603
    MULTIPART("multipart/form-data"),
604
    BINARY("application/octet-stream"),
605
    ANY("*/*");
606
    
607
    String toString();
608
    String getContentTypeStrings();
609
    boolean matches(String contentType);
610
}
611

612
// Multipart specification
613
interface MultiPartSpecification {
614
    String getControlName();
615
    String getMimeType();
616
    String getFileName();
617
    Object getContent();
618
}
619
```