0
# HTTP Client Core
1

2
The core HTTP client functionality provides the main `HttpClient` class for making asynchronous HTTP requests with full coroutines support. It offers both convenience methods for common HTTP verbs and advanced request building capabilities.
3

4
## Core Types
5

6
```kotlin { .api }
7
// HttpClient class (main constructor is internal)
8
class HttpClient(
9
    public val engine: HttpClientEngine,
10
    private val userConfig: HttpClientConfig<out HttpClientEngineConfig> = HttpClientConfig()
11
) : CoroutineScope, Closeable {
12
    public val attributes: Attributes
13
    public val engineConfig: HttpClientEngineConfig
14
    public val monitor: Events
15
    public val requestPipeline: HttpRequestPipeline
16
    public val responsePipeline: HttpResponsePipeline
17
    public val sendPipeline: HttpSendPipeline
18
    public val receivePipeline: HttpReceivePipeline
19
    
20
    public fun isSupported(capability: HttpClientEngineCapability<*>): Boolean
21
    public fun config(block: HttpClientConfig<*>.() -> Unit): HttpClient
22
    override fun close()
23
}
24

25
// HTTP method extensions (all are extension functions, not class members)
26
suspend fun HttpClient.get(builder: HttpRequestBuilder): HttpResponse
27
suspend fun HttpClient.get(block: HttpRequestBuilder.() -> Unit): HttpResponse
28
suspend fun HttpClient.get(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
29
suspend fun HttpClient.get(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
30

31
suspend fun HttpClient.post(builder: HttpRequestBuilder): HttpResponse
32
suspend fun HttpClient.post(block: HttpRequestBuilder.() -> Unit): HttpResponse
33
suspend fun HttpClient.post(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
34
suspend fun HttpClient.post(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
35

36
suspend fun HttpClient.put(builder: HttpRequestBuilder): HttpResponse
37
suspend fun HttpClient.put(block: HttpRequestBuilder.() -> Unit): HttpResponse
38
suspend fun HttpClient.put(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
39
suspend fun HttpClient.put(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
40

41
suspend fun HttpClient.delete(builder: HttpRequestBuilder): HttpResponse
42
suspend fun HttpClient.delete(block: HttpRequestBuilder.() -> Unit): HttpResponse
43
suspend fun HttpClient.delete(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
44
suspend fun HttpClient.delete(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
45

46
suspend fun HttpClient.head(builder: HttpRequestBuilder): HttpResponse
47
suspend fun HttpClient.head(block: HttpRequestBuilder.() -> Unit): HttpResponse
48
suspend fun HttpClient.head(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
49
suspend fun HttpClient.head(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
50

51
suspend fun HttpClient.options(builder: HttpRequestBuilder): HttpResponse
52
suspend fun HttpClient.options(block: HttpRequestBuilder.() -> Unit): HttpResponse
53
suspend fun HttpClient.options(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
54
suspend fun HttpClient.options(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
55

56
suspend fun HttpClient.patch(builder: HttpRequestBuilder): HttpResponse
57
suspend fun HttpClient.patch(block: HttpRequestBuilder.() -> Unit): HttpResponse
58
suspend fun HttpClient.patch(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
59
suspend fun HttpClient.patch(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
60

61
// Generic request methods
62
suspend fun HttpClient.request(builder: HttpRequestBuilder = HttpRequestBuilder()): HttpResponse
63
suspend fun HttpClient.request(block: HttpRequestBuilder.() -> Unit): HttpResponse
64
suspend fun HttpClient.request(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
65
suspend fun HttpClient.request(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpResponse
66

67
// Prepared statement extensions
68
suspend fun HttpClient.prepareGet(builder: HttpRequestBuilder): HttpStatement
69
suspend fun HttpClient.prepareGet(block: HttpRequestBuilder.() -> Unit): HttpStatement
70
suspend fun HttpClient.prepareGet(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
71
suspend fun HttpClient.prepareGet(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
72

73
suspend fun HttpClient.preparePost(builder: HttpRequestBuilder): HttpStatement
74
suspend fun HttpClient.preparePost(block: HttpRequestBuilder.() -> Unit): HttpStatement
75
suspend fun HttpClient.preparePost(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
76
suspend fun HttpClient.preparePost(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
77

78
suspend fun HttpClient.preparePut(builder: HttpRequestBuilder): HttpStatement
79
suspend fun HttpClient.preparePut(block: HttpRequestBuilder.() -> Unit): HttpStatement
80
suspend fun HttpClient.preparePut(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
81
suspend fun HttpClient.preparePut(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
82

83
suspend fun HttpClient.prepareDelete(builder: HttpRequestBuilder): HttpStatement
84
suspend fun HttpClient.prepareDelete(block: HttpRequestBuilder.() -> Unit): HttpStatement
85
suspend fun HttpClient.prepareDelete(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
86
suspend fun HttpClient.prepareDelete(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
87

88
suspend fun HttpClient.prepareHead(builder: HttpRequestBuilder): HttpStatement
89
suspend fun HttpClient.prepareHead(block: HttpRequestBuilder.() -> Unit): HttpStatement
90
suspend fun HttpClient.prepareHead(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
91
suspend fun HttpClient.prepareHead(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
92

93
suspend fun HttpClient.prepareOptions(builder: HttpRequestBuilder): HttpStatement
94
suspend fun HttpClient.prepareOptions(block: HttpRequestBuilder.() -> Unit): HttpStatement
95
suspend fun HttpClient.prepareOptions(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
96
suspend fun HttpClient.prepareOptions(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
97

98
suspend fun HttpClient.preparePatch(builder: HttpRequestBuilder): HttpStatement
99
suspend fun HttpClient.preparePatch(block: HttpRequestBuilder.() -> Unit): HttpStatement
100
suspend fun HttpClient.preparePatch(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
101
suspend fun HttpClient.preparePatch(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
102

103
suspend fun HttpClient.prepareRequest(builder: HttpRequestBuilder = HttpRequestBuilder()): HttpStatement
104
suspend fun HttpClient.prepareRequest(block: HttpRequestBuilder.() -> Unit): HttpStatement
105
suspend fun HttpClient.prepareRequest(urlString: String, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
106
suspend fun HttpClient.prepareRequest(url: Url, block: HttpRequestBuilder.() -> Unit = {}): HttpStatement
107
```
108

109
## Client Configuration
110

111
```kotlin { .api }
112
class HttpClientConfig<T : HttpClientEngineConfig> {
113
    var expectSuccess: Boolean = true
114
    var followRedirects: Boolean = true  
115
    var useDefaultTransformers: Boolean = true
116
    var developmentMode: Boolean = false
117
    
118
    fun <P : Any, B : Any> install(
119
        plugin: HttpClientPlugin<P, B>,
120
        configure: P.() -> Unit = {}
121
    )
122
    
123
    fun engine(factory: HttpClientEngineFactory<T>, configure: T.() -> Unit = {})
124
}
125
```
126

127
## Client Creation
128

129
### Default Client
130
```kotlin
131
// Creates client with default engine for the platform
132
val client = HttpClient()
133
```
134

135
### Client with Configuration
136
```kotlin
137
val client = HttpClient {
138
    expectSuccess = false
139
    followRedirects = true
140
    
141
    // Install plugins
142
    install(HttpTimeout) {
143
        requestTimeoutMillis = 30000
144
        connectTimeoutMillis = 10000
145
    }
146
}
147
```
148

149
### Client with Specific Engine
150
```kotlin
151
// Using engine factory
152
val client = HttpClient(engineFactory) {
153
    // Configure engine-specific settings
154
}
155

156
// Using engine instance
157
val engine = engineFactory.create {
158
    // Engine configuration
159
}
160
val client = HttpClient(engine)
161
```
162

163
## Making Requests
164

165
### Simple GET Request
166
```kotlin
167
val response: HttpResponse = client.get("https://api.example.com/users")
168
val text: String = response.bodyAsText()
169
```
170

171
### POST with Body
172
```kotlin
173
val response = client.post("https://api.example.com/users") {
174
    setBody("{ \"name\": \"John\", \"email\": \"john@example.com\" }")
175
    header("Content-Type", "application/json")
176
}
177
```
178

179
### Generic Request with Full Configuration
180
```kotlin
181
val response = client.request {
182
    method = HttpMethod.Post
183
    url("https://api.example.com/users")
184
    header("Authorization", "Bearer $token")
185
    parameter("expand", "profile")
186
    setBody(userData)
187
}
188
```
189

190
### Using Prepared Statements
191
```kotlin
192
// Prepare request for reuse
193
val statement = client.preparePost("https://api.example.com/users") {
194
    header("Content-Type", "application/json")
195
}
196

197
// Execute with different bodies
198
val response1 = statement.execute { setBody(user1) }
199
val response2 = statement.execute { setBody(user2) }
200
```
201

202
## Lifecycle Management
203

204
### Closing the Client
205
```kotlin
206
// Always close the client when done
207
client.close()
208
```
209

210
### Using with Resources
211
```kotlin
212
HttpClient().use { client ->
213
    val response = client.get("https://api.example.com/data")
214
    // Client automatically closed when exiting block
215
}
216
```
217

218
## Error Handling
219

220
### Basic Error Handling
221
```kotlin
222
try {
223
    val response = client.get("https://api.example.com/users")
224
    if (response.status.isSuccess()) {
225
        val data = response.bodyAsText()
226
        // Process successful response
227
    } else {
228
        println("Request failed: ${response.status}")
229
    }
230
} catch (e: Exception) {
231
    println("Network error: ${e.message}")
232
}
233
```
234

235
### Timeout Exceptions
236
```kotlin
237
import io.ktor.client.network.sockets.*
238

239
try {
240
    val response = client.get("https://slow-api.example.com")
241
} catch (e: ConnectTimeoutException) {
242
    println("Connection timeout")
243
} catch (e: SocketTimeoutException) {
244
    println("Read timeout")
245
}
246
```
247

248
## Client Events
249

250
The client provides events for monitoring request lifecycle:
251

252
```kotlin { .api }
253
object HttpRequestCreated : EventDefinition<HttpRequestBuilder>()
254
object HttpRequestIsReadyForSending : EventDefinition<HttpRequest>()
255
object HttpResponseReceived : EventDefinition<HttpResponseContainer>()
256
object HttpResponseCancelled : EventDefinition<HttpResponseContainer>()
257
```
258

259
### Monitoring Events
260
```kotlin
261
client.monitor.subscribe(HttpRequestCreated) { request ->
262
    println("Request created: ${request.method} ${request.url}")
263
}
264

265
client.monitor.subscribe(HttpResponseReceived) { container ->
266
    println("Response received: ${container.response.status}")
267
}
268
```