0
# HTTP Requests
1

2
Comprehensive HTTP request functionality including all standard methods, request building, URL construction, and parameter handling.
3

4
## Capabilities
5

6
### HTTP Method Functions
7

8
Standard HTTP method convenience functions for making requests.
9

10
```kotlin { .api }
11
/**
12
 * Make a GET request
13
 * @param urlString Target URL
14
 * @param block Optional request configuration
15
 * @returns HttpResponse
16
 */
17
suspend fun HttpClient.get(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
18

19
/**
20
 * Make a POST request
21
 * @param urlString Target URL
22
 * @param block Optional request configuration
23
 * @returns HttpResponse
24
 */
25
suspend fun HttpClient.post(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
26

27
/**
28
 * Make a PUT request
29
 * @param urlString Target URL
30
 * @param block Optional request configuration
31
 * @returns HttpResponse
32
 */
33
suspend fun HttpClient.put(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
34

35
/**
36
 * Make a DELETE request
37
 * @param urlString Target URL
38
 * @param block Optional request configuration
39
 * @returns HttpResponse
40
 */
41
suspend fun HttpClient.delete(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
42

43
/**
44
 * Make a HEAD request
45
 * @param urlString Target URL
46
 * @param block Optional request configuration
47
 * @returns HttpResponse
48
 */
49
suspend fun HttpClient.head(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
50

51
/**
52
 * Make a PATCH request
53
 * @param urlString Target URL
54
 * @param block Optional request configuration
55
 * @returns HttpResponse
56
 */
57
suspend fun HttpClient.patch(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
58

59
/**
60
 * Make an OPTIONS request
61
 * @param urlString Target URL
62
 * @param block Optional request configuration
63
 * @returns HttpResponse
64
 */
65
suspend fun HttpClient.options(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
66
```
67

68
**Usage Examples:**
69

70
```kotlin
71
val client = HttpClient()
72

73
// Simple GET request
74
val response = client.get("https://api.example.com/users")
75

76
// POST with JSON body
77
val postResponse = client.post("https://api.example.com/users") {
78
    setBody("""{"name": "John", "email": "john@example.com"}""")
79
    header("Content-Type", "application/json")
80
}
81

82
// PUT with parameters
83
val putResponse = client.put("https://api.example.com/users/123") {
84
    parameter("version", "2")
85
    setBody("""{"name": "Jane", "email": "jane@example.com"}""")
86
}
87

88
// DELETE with authentication
89
val deleteResponse = client.delete("https://api.example.com/users/123") {
90
    bearerAuth("your-token-here")
91
}
92
```
93

94
### Request Preparation Functions
95

96
Prepare requests without immediately executing them.
97

98
```kotlin { .api }
99
/**
100
 * Prepare a GET request without executing it
101
 * @param urlString Target URL
102
 * @param block Optional request configuration
103
 * @returns HttpStatement ready for execution
104
 */
105
suspend fun HttpClient.prepareGet(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
106

107
/**
108
 * Prepare a POST request without executing it
109
 * @param urlString Target URL
110
 * @param block Optional request configuration
111
 * @returns HttpStatement ready for execution
112
 */
113
suspend fun HttpClient.preparePost(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
114

115
/**
116
 * Prepare a PUT request without executing it
117
 * @param urlString Target URL
118
 * @param block Optional request configuration
119
 * @returns HttpStatement ready for execution
120
 */
121
suspend fun HttpClient.preparePut(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
122

123
/**
124
 * Prepare a DELETE request without executing it
125
 * @param urlString Target URL
126
 * @param block Optional request configuration
127
 * @returns HttpStatement ready for execution
128
 */
129
suspend fun HttpClient.prepareDelete(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
130

131
/**
132
 * Prepare a HEAD request without executing it
133
 * @param urlString Target URL
134
 * @param block Optional request configuration
135
 * @returns HttpStatement ready for execution
136
 */
137
suspend fun HttpClient.prepareHead(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
138

139
/**
140
 * Prepare a PATCH request without executing it
141
 * @param urlString Target URL
142
 * @param block Optional request configuration
143
 * @returns HttpStatement ready for execution
144
 */
145
suspend fun HttpClient.preparePatch(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
146

147
/**
148
 * Prepare an OPTIONS request without executing it
149
 * @param urlString Target URL
150
 * @param block Optional request configuration
151
 * @returns HttpStatement ready for execution
152
 */
153
suspend fun HttpClient.prepareOptions(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
154

155
/**
156
 * Prepare a generic request without executing it
157
 * @param block Request configuration including method and URL
158
 * @returns HttpStatement ready for execution
159
 */
160
suspend fun HttpClient.prepareRequest(block: HttpRequestBuilder.() -> Unit): HttpStatement
161
```
162

163
**Usage Examples:**
164

165
```kotlin
166
// Prepare request for later execution
167
val statement = client.prepareGet("https://api.example.com/users") {
168
    parameter("page", "1")
169
    header("Accept", "application/json")
170
}
171

172
// Execute when ready
173
val response = statement.execute()
174

175
// Or execute with custom response handling
176
val result = statement.execute { response ->
177
    response.bodyAsText()
178
}
179
```
180

181
### Generic Request Functions
182

183
Generic request methods for custom HTTP methods and advanced configuration.
184

185
```kotlin { .api }
186
/**
187
 * Make a generic HTTP request
188
 * @param block Request configuration including method, URL, and options
189
 * @returns HttpResponse
190
 */
191
suspend fun HttpClient.request(block: HttpRequestBuilder.() -> Unit): HttpResponse
192

193
/**
194
 * Make a generic HTTP request with URL
195
 * @param urlString Target URL
196
 * @param block Request configuration
197
 * @returns HttpResponse
198
 */
199
suspend fun HttpClient.request(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
200
```
201

202
**Usage Examples:**
203

204
```kotlin
205
// Custom HTTP method
206
val response = client.request {
207
    method = HttpMethod.Parse("CUSTOM")
208
    url("https://api.example.com/custom-endpoint")
209
    setBody("custom body")
210
}
211

212
// Complex request configuration
213
val complexResponse = client.request("https://api.example.com/data") {
214
    method = HttpMethod.Get
215
    parameter("filter", "active")
216
    parameter("sort", "name")
217
    headers {
218
        append("Custom-Header", "value")
219
        append("Accept-Language", "en-US")
220
    }
221
    timeout {
222
        requestTimeoutMillis = 60000
223
    }
224
}
225
```
226

227
### HttpRequestBuilder Class
228

229
Main class for building HTTP requests with comprehensive configuration options.
230

231
```kotlin { .api }
232
/**
233
 * Builder class for constructing HTTP requests
234
 */
235
class HttpRequestBuilder {
236
    /** HTTP method for the request */
237
    var method: HttpMethod
238
    
239
    /** Request body content */
240
    var body: Any?
241
    
242
    /** Request headers */
243
    val headers: HeadersBuilder
244
    
245
    /** URL components */
246
    val url: URLBuilder
247
    
248
    /** Request attributes for plugins */
249
    val attributes: Attributes
250
    
251
    /**
252
     * Set the request body
253
     * @param body Body content (String, ByteArray, OutgoingContent, etc.)
254
     */
255
    fun setBody(body: Any?)
256
    
257
    /**
258
     * Add a URL parameter
259
     * @param key Parameter name
260
     * @param value Parameter value
261
     */
262
    fun parameter(key: String, value: Any?)
263
    
264
    /**
265
     * Add a request header
266
     * @param key Header name
267
     * @param value Header value
268
     */
269
    fun header(key: String, value: String)
270
    
271
    /**
272
     * Configure headers using a builder
273
     * @param block Header configuration block
274
     */
275
    fun headers(block: HeadersBuilder.() -> Unit)
276
    
277
    /**
278
     * Configure URL using a builder
279
     * @param block URL configuration block
280
     */
281
    fun url(block: URLBuilder.() -> Unit)
282
    
283
    /**
284
     * Set Content-Type header
285
     * @param contentType Content type value
286
     */
287
    fun contentType(contentType: ContentType)
288
    
289
    /**
290
     * Set Accept header
291
     * @param contentType Accepted content type
292
     */
293
    fun accept(contentType: ContentType)
294
    
295
    /**
296
     * Set Bearer token authorization
297
     * @param token Bearer token
298
     */
299
    fun bearerAuth(token: String)
300
    
301
    /**
302
     * Set Basic authentication
303
     * @param username Username
304
     * @param password Password
305
     */
306
    fun basicAuth(username: String, password: String)
307
    
308
    /**
309
     * Configure request timeout
310
     * @param block Timeout configuration
311
     */
312
    fun timeout(block: HttpTimeoutCapabilityConfiguration.() -> Unit)
313
}
314
```
315

316
**Usage Examples:**
317

318
```kotlin
319
val response = client.post("https://api.example.com/data") {
320
    // Set request method (usually inferred from function)
321
    method = HttpMethod.Post
322
    
323
    // Configure URL
324
    url {
325
        protocol = URLProtocol.HTTPS
326
        host = "api.example.com"
327
        path("data", "upload")
328
        parameter("version", "2")
329
    }
330
    
331
    // Set headers
332
    header("Custom-Header", "value")
333
    headers {
334
        append("Accept", "application/json")
335
        append("User-Agent", "MyApp/1.0")
336
    }
337
    
338
    // Set body
339
    setBody("""{"data": "example"}""")
340
    contentType(ContentType.Application.Json)
341
    
342
    // Authentication
343
    bearerAuth("your-token-here")
344
    
345
    // Timeout for this request
346
    timeout {
347
        requestTimeoutMillis = 30000
348
    }
349
}
350
```
351

352
### URL and Parameter Functions
353

354
Functions for URL construction and parameter management.
355

356
```kotlin { .api }
357
/**
358
 * Configure URL using string
359
 * @param urlString URL string
360
 */
361
fun HttpRequestBuilder.url(urlString: String)
362

363
/**
364
 * Configure URL using URL object
365
 * @param url URL object
366
 */
367
fun HttpRequestBuilder.url(url: Url)
368

369
/**
370
 * Add multiple parameters from Parameters object
371
 * @param parameters Parameters to add
372
 */
373
fun HttpRequestBuilder.parameter(parameters: Parameters)
374

375
/**
376
 * Add parameter only if value is not null
377
 * @param key Parameter name
378
 * @param value Parameter value (nullable)
379
 */
380
fun HttpRequestBuilder.parameterNotNull(key: String, value: Any?)
381
```
382

383
### Header Management Functions
384

385
Advanced header manipulation functions.
386

387
```kotlin { .api }
388
/**
389
 * Set User-Agent header
390
 * @param userAgent User agent string
391
 */
392
fun HttpRequestBuilder.userAgent(userAgent: String)
393

394
/**
395
 * Set multiple headers from a map
396
 * @param headers Map of header names to values
397
 */
398
fun HttpRequestBuilder.headers(headers: Map<String, String>)
399

400
/**
401
 * Configure headers with conditional logic
402
 * @param block Header configuration block
403
 */
404
fun HttpRequestBuilder.headers(block: HeadersBuilder.() -> Unit)
405
```
406

407
**Usage Examples:**
408

409
```kotlin
410
client.get("https://api.example.com/users") {
411
    // URL configuration
412
    url {
413
        parameter("page", 1)
414
        parameter("limit", 50)
415
        fragment = "results"
416
    }
417
    
418
    // Header management
419
    userAgent("MyApp/1.0")
420
    headers {
421
        if (needsAuth) {
422
            append("Authorization", "Bearer $token")
423
        }
424
        append("Accept-Language", "en-US,en;q=0.9")
425
    }
426
    
427
    // Conditional parameters
428
    parameterNotNull("filter", activeFilter)
429
}
430
```
431

432
## Types
433

434
### Request Types
435

436
```kotlin { .api }
437
/**
438
 * HTTP request representation
439
 */
440
interface HttpRequest {
441
    val call: HttpClientCall
442
    val method: HttpMethod
443
    val url: Url
444
    val content: OutgoingContent
445
    val headers: Headers
446
    val attributes: Attributes
447
}
448

449
/**
450
 * Default implementation of HttpRequest
451
 */
452
class DefaultHttpRequest(
453
    override val call: HttpClientCall,
454
    override val method: HttpMethod,
455
    override val url: Url,
456
    override val content: OutgoingContent,
457
    override val headers: Headers,
458
    override val attributes: Attributes
459
) : HttpRequest
460

461
/**
462
 * HTTP method enumeration
463
 */
464
data class HttpMethod(val value: String) {
465
    companion object {
466
        val Get: HttpMethod
467
        val Post: HttpMethod
468
        val Put: HttpMethod
469
        val Delete: HttpMethod
470
        val Head: HttpMethod
471
        val Options: HttpMethod
472
        val Patch: HttpMethod
473
        
474
        fun parse(method: String): HttpMethod
475
    }
476
}
477

478
/**
479
 * Request body content types
480
 */
481
sealed class OutgoingContent {
482
    object NoContent : OutgoingContent()
483
    abstract class ByteArrayContent : OutgoingContent()
484
    abstract class ReadChannelContent : OutgoingContent()
485
    abstract class WriteChannelContent : OutgoingContent()
486
    abstract class ProtocolUpgrade : OutgoingContent()
487
}
488
```
489

490
### URL and Parameter Types
491

492
```kotlin { .api }
493
/**
494
 * URL builder for constructing URLs
495
 */
496
class URLBuilder {
497
    var protocol: URLProtocol
498
    var host: String
499
    var port: Int
500
    var user: String?
501
    var password: String?
502
    var pathSegments: MutableList<String>
503
    var parameters: ParametersBuilder
504
    var fragment: String
505
    var trailingQuery: Boolean
506
    
507
    fun path(vararg components: String)
508
    fun path(components: List<String>)
509
    fun build(): Url
510
}
511

512
/**
513
 * Parameters collection
514
 */
515
interface Parameters {
516
    val caseInsensitiveName: Boolean
517
    fun getAll(name: String): List<String>?
518
    fun names(): Set<String>
519
    fun isEmpty(): Boolean
520
    
521
    companion object {
522
        val Empty: Parameters
523
        
524
        fun build(block: ParametersBuilder.() -> Unit): Parameters
525
    }
526
}
527

528
/**
529
 * Parameters builder
530
 */
531
class ParametersBuilder {
532
    fun append(name: String, value: String)
533
    fun appendAll(parameters: Parameters)
534
    fun appendAll(parameters: StringValues)
535
    fun build(): Parameters
536
}
537
```