0
# HTTP Request Operations
1

2
HTTP method extensions and request building functionality for making various types of HTTP requests with type-safe configuration.
3

4
## Capabilities
5

6
### HTTP Method Extensions
7

8
Convenient extension functions for common HTTP methods with various parameter combinations.
9

10
```kotlin { .api }
11
/**
12
 * Perform a GET request
13
 * @param urlString The URL to request
14
 * @param block Configuration block for the request
15
 * @return HttpResponse from the server
16
 */
17
suspend fun HttpClient.get(
18
    urlString: String,
19
    block: HttpRequestBuilder.() -> Unit = {}
20
): HttpResponse
21

22
suspend fun HttpClient.get(
23
    url: Url,
24
    block: HttpRequestBuilder.() -> Unit = {}
25
): HttpResponse
26

27
suspend fun HttpClient.get(
28
    block: HttpRequestBuilder.() -> Unit
29
): HttpResponse
30

31
/**
32
 * Perform a POST request
33
 * @param urlString The URL to request
34
 * @param block Configuration block for the request
35
 * @return HttpResponse from the server
36
 */
37
suspend fun HttpClient.post(
38
    urlString: String,
39
    block: HttpRequestBuilder.() -> Unit = {}
40
): HttpResponse
41

42
suspend fun HttpClient.post(
43
    url: Url,
44
    block: HttpRequestBuilder.() -> Unit = {}
45
): HttpResponse
46

47
suspend fun HttpClient.post(
48
    block: HttpRequestBuilder.() -> Unit
49
): HttpResponse
50

51
/**
52
 * Perform a PUT request
53
 * @param urlString The URL to request
54
 * @param block Configuration block for the request
55
 * @return HttpResponse from the server
56
 */
57
suspend fun HttpClient.put(
58
    urlString: String,
59
    block: HttpRequestBuilder.() -> Unit = {}
60
): HttpResponse
61

62
/**
63
 * Perform a DELETE request
64
 * @param urlString The URL to request
65
 * @param block Configuration block for the request
66
 * @return HttpResponse from the server
67
 */
68
suspend fun HttpClient.delete(
69
    urlString: String,
70
    block: HttpRequestBuilder.() -> Unit = {}
71
): HttpResponse
72

73
/**
74
 * Perform a PATCH request
75
 * @param urlString The URL to request
76
 * @param block Configuration block for the request
77
 * @return HttpResponse from the server
78
 */
79
suspend fun HttpClient.patch(
80
    urlString: String,
81
    block: HttpRequestBuilder.() -> Unit = {}
82
): HttpResponse
83

84
/**
85
 * Perform an OPTIONS request
86
 * @param urlString The URL to request
87
 * @param block Configuration block for the request
88
 * @return HttpResponse from the server
89
 */
90
suspend fun HttpClient.options(
91
    urlString: String,
92
    block: HttpRequestBuilder.() -> Unit = {}
93
): HttpResponse
94

95
/**
96
 * Perform a HEAD request
97
 * @param urlString The URL to request
98
 * @param block Configuration block for the request
99
 * @return HttpResponse from the server
100
 */
101
suspend fun HttpClient.head(
102
    urlString: String,
103
    block: HttpRequestBuilder.() -> Unit = {}
104
): HttpResponse
105
```
106

107
**Usage Examples:**
108

109
```kotlin
110
import io.ktor.client.*
111
import io.ktor.client.request.*
112
import io.ktor.http.*
113

114
val client = HttpClient()
115

116
// Simple GET request
117
val response = client.get("https://api.example.com/users")
118

119
// POST with body and headers
120
val postResponse = client.post("https://api.example.com/users") {
121
    header(HttpHeaders.ContentType, ContentType.Application.Json)
122
    setBody("""{"name": "John", "email": "john@example.com"}""")
123
}
124

125
// PUT with query parameters
126
val putResponse = client.put("https://api.example.com/users/123") {
127
    parameter("include", "profile")
128
    setBody(userUpdateData)
129
}
130

131
// DELETE request
132
val deleteResponse = client.delete("https://api.example.com/users/123")
133
```
134

135
### Prepared Request Extensions
136

137
Extensions that return HttpStatement for deferred execution, allowing for more control over request execution.
138

139
```kotlin { .api }
140
/**
141
 * Prepare a GET request for deferred execution
142
 * @param urlString The URL to request
143
 * @param block Configuration block for the request
144
 * @return HttpStatement for deferred execution
145
 */
146
suspend fun HttpClient.prepareGet(
147
    urlString: String,
148
    block: HttpRequestBuilder.() -> Unit = {}
149
): HttpStatement
150

151
suspend fun HttpClient.preparePost(
152
    urlString: String,
153
    block: HttpRequestBuilder.() -> Unit = {}
154
): HttpStatement
155

156
suspend fun HttpClient.preparePut(
157
    urlString: String,
158
    block: HttpRequestBuilder.() -> Unit = {}
159
): HttpStatement
160

161
suspend fun HttpClient.prepareDelete(
162
    urlString: String,
163
    block: HttpRequestBuilder.() -> Unit = {}
164
): HttpStatement
165

166
suspend fun HttpClient.preparePatch(
167
    urlString: String,
168
    block: HttpRequestBuilder.() -> Unit = {}
169
): HttpStatement
170

171
suspend fun HttpClient.prepareOptions(
172
    urlString: String,
173
    block: HttpRequestBuilder.() -> Unit = {}
174
): HttpStatement
175

176
suspend fun HttpClient.prepareHead(
177
    urlString: String,
178
    block: HttpRequestBuilder.() -> Unit = {}
179
): HttpStatement
180
```
181

182
**Usage Examples:**
183

184
```kotlin
185
import io.ktor.client.*
186
import io.ktor.client.request.*
187
import io.ktor.client.statement.*
188

189
val client = HttpClient()
190

191
// Prepare request for later execution
192
val statement = client.prepareGet("https://api.example.com/users")
193

194
// Execute the request
195
val response = statement.execute()
196

197
// Or execute with custom handling
198
val result = statement.execute { response ->
199
    if (response.status.isSuccess()) {
200
        response.bodyAsText()
201
    } else {
202
        "Error: ${response.status}"
203
    }
204
}
205
```
206

207
### Generic Request Methods
208

209
Generic request functions that accept any HTTP method and provide maximum flexibility.
210

211
```kotlin { .api }
212
/**
213
 * Perform a generic HTTP request
214
 * @param block Configuration block for the request
215
 * @return HttpResponse from the server
216
 */
217
suspend fun HttpClient.request(
218
    block: HttpRequestBuilder.() -> Unit
219
): HttpResponse
220

221
suspend fun HttpClient.request(
222
    urlString: String,
223
    block: HttpRequestBuilder.() -> Unit = {}
224
): HttpResponse
225

226
suspend fun HttpClient.request(
227
    url: Url,
228
    block: HttpRequestBuilder.() -> Unit = {}
229
): HttpResponse
230

231
/**
232
 * Prepare a generic HTTP request for deferred execution
233
 * @param block Configuration block for the request
234
 * @return HttpStatement for deferred execution
235
 */
236
suspend fun HttpClient.prepareRequest(
237
    block: HttpRequestBuilder.() -> Unit
238
): HttpStatement
239

240
suspend fun HttpClient.prepareRequest(
241
    urlString: String,
242
    block: HttpRequestBuilder.() -> Unit = {}
243
): HttpStatement
244
```
245

246
**Usage Examples:**
247

248
```kotlin
249
import io.ktor.client.*
250
import io.ktor.client.request.*
251
import io.ktor.http.*
252

253
val client = HttpClient()
254

255
// Generic request with custom method
256
val response = client.request {
257
    method = HttpMethod.Patch
258
    url("https://api.example.com/users/123")
259
    header("Authorization", "Bearer $token")
260
    setBody(patchData)
261
}
262

263
// Prepared generic request
264
val statement = client.prepareRequest("https://api.example.com/data") {
265
    method = HttpMethod.Get
266
    parameter("limit", 50)
267
}
268
```
269

270
### HttpRequestBuilder Class
271

272
Mutable builder for constructing HTTP requests with DSL syntax.
273

274
```kotlin { .api }
275
/**
276
 * Builder for constructing HTTP requests
277
 */
278
class HttpRequestBuilder : HttpMessageBuilder {
279
    /** URL builder for the request */
280
    val url: URLBuilder
281
    
282
    /** HTTP method for the request */
283
    var method: HttpMethod = HttpMethod.Get
284
    
285
    /** Headers builder for the request */
286
    override val headers: HeadersBuilder
287
    
288
    /** Request body content */
289
    var body: Any = EmptyContent
290
    
291
    /** Type information for the body */
292
    var bodyType: TypeInfo?
293
    
294
    /** Execution context for the request */
295
    var executionContext: Job
296
    
297
    /** Attributes for storing request metadata */
298
    val attributes: Attributes
299
    
300
    /**
301
     * Configure the URL
302
     * @param block Configuration block for URLBuilder
303
     */
304
    fun url(block: URLBuilder.(URLBuilder) -> Unit)
305
    
306
    /**
307
     * Build the final request data
308
     * @return Immutable HttpRequestData
309
     */
310
    fun build(): HttpRequestData
311
    
312
    /**
313
     * Configure request attributes
314
     * @param block Configuration block for attributes
315
     */
316
    fun setAttributes(block: Attributes.() -> Unit)
317
    
318
    /**
319
     * Set an engine capability
320
     * @param key The capability key
321
     * @param capability The capability value
322
     */
323
    fun <T : Any> setCapability(
324
        key: HttpClientEngineCapability<T>,
325
        capability: T
326
    )
327
    
328
    /**
329
     * Get an engine capability
330
     * @param key The capability key
331
     * @return Capability value or null if not set
332
     */
333
    fun <T : Any> getCapabilityOrNull(
334
        key: HttpClientEngineCapability<T>
335
    ): T?
336
}
337
```
338

339
**Usage Examples:**
340

341
```kotlin
342
import io.ktor.client.*
343
import io.ktor.client.request.*
344
import io.ktor.http.*
345

346
// Using request builder in a request block
347
val response = client.post {
348
    // Configure URL
349
    url {
350
        protocol = URLProtocol.HTTPS
351
        host = "api.example.com"
352
        path("users")
353
    }
354
    
355
    // Set method and headers
356
    method = HttpMethod.Post
357
    header("Content-Type", "application/json")
358
    header("Authorization", "Bearer $token")
359
    
360
    // Set body
361
    setBody(userData)
362
    
363
    // Configure attributes
364
    setAttributes {
365
        put(customAttribute, "value")
366
    }
367
}
368
```
369

370
### HttpRequestData Class
371

372
Immutable request data that is passed to HTTP engines for execution.
373

374
```kotlin { .api }
375
/**
376
 * Immutable HTTP request data
377
 */
378
class HttpRequestData(
379
    val url: Url,
380
    val method: HttpMethod,
381
    val headers: Headers,
382
    val body: OutgoingContent,
383
    val executionContext: Job,
384
    val attributes: Attributes
385
) {
386
    /**
387
     * Get an engine capability
388
     * @param key The capability key
389
     * @return Capability value or null if not set
390
     */
391
    fun <T> getCapabilityOrNull(
392
        key: HttpClientEngineCapability<T>
393
    ): T?
394
    
395
    /** Set of required engine capabilities */
396
    internal val requiredCapabilities: Set<HttpClientEngineCapability<*>>
397
}
398
```
399

400
### Request Configuration Extensions
401

402
Utility extensions for common request configuration patterns.
403

404
```kotlin { .api }
405
/**
406
 * Set request header
407
 * @param key Header name
408
 * @param value Header value
409
 */
410
fun HttpMessageBuilder.header(key: String, value: Any?)
411

412
/**
413
 * Configure headers
414
 * @param block Configuration block for headers
415
 * @return HeadersBuilder instance
416
 */
417
fun HttpMessageBuilder.headers(
418
    block: HeadersBuilder.() -> Unit
419
): HeadersBuilder
420

421
/**
422
 * Set User-Agent header
423
 * @param agent User agent string
424
 */
425
fun HttpRequestBuilder.userAgent(agent: String)
426

427
/**
428
 * Set Accept header
429
 * @param contentType Content type to accept
430
 */
431
fun HttpRequestBuilder.accept(contentType: ContentType)
432

433
/**
434
 * Set request body
435
 * @param body Body content
436
 */
437
fun HttpRequestBuilder.setBody(body: Any)
438

439
/**
440
 * Add URL parameter
441
 * @param key Parameter name
442
 * @param value Parameter value
443
 */
444
fun HttpRequestBuilder.parameter(key: String, value: Any?)
445
```
446

447
**Usage Examples:**
448

449
```kotlin
450
import io.ktor.client.*
451
import io.ktor.client.request.*
452
import io.ktor.http.*
453

454
val response = client.get("https://api.example.com/users") {
455
    // Headers
456
    header("X-Custom-Header", "value")
457
    userAgent("MyApp/1.0")
458
    accept(ContentType.Application.Json)
459
    
460
    // Parameters
461
    parameter("limit", 10)
462
    parameter("offset", 0)
463
    parameter("include", "profile")
464
}
465
```
466

467
## Types
468

469
Request operation related types:
470

471
```kotlin { .api }
472
/**
473
 * HTTP methods enumeration
474
 */
475
enum class HttpMethod(val value: String) {
476
    Get("GET"),
477
    Post("POST"),
478
    Put("PUT"),
479
    Delete("DELETE"),
480
    Head("HEAD"),
481
    Options("OPTIONS"),
482
    Patch("PATCH")
483
}
484

485
/**
486
 * URL builder for constructing URLs
487
 */
488
class URLBuilder {
489
    var protocol: URLProtocol
490
    var host: String
491
    var port: Int
492
    var pathSegments: List<String>
493
    var parameters: ParametersBuilder
494
    var fragment: String
495
    
496
    fun path(vararg components: String)
497
    fun build(): Url
498
}
499

500
/**
501
 * Parameters builder for URL parameters
502
 */
503
interface ParametersBuilder {
504
    fun append(name: String, value: String)
505
    fun appendAll(name: String, values: Iterable<String>)
506
    fun set(name: String, value: String)
507
    fun remove(name: String)
508
    fun clear()
509
}
510

511
/**
512
 * Empty content object for requests without body
513
 */
514
object EmptyContent : OutgoingContent.NoContent()
515
```