Client

note

This help topic is in development and will be updated in the future.

Adding an engine dependency

The first thing you need to do before using the client is to add a client engine dependency. Client engine is a request executor that performs requests from ktor API. There are many client engines for each platform available out of the box: Apache, OkHttp, Android, Ios, Js, Jetty, CIO and Mock. You can read more in the Multiplatform section.

For example, you can add CIO engine dependency in build.gradle like this:

dependencies {
    implementation("io.ktor:ktor-client-cio:$ktor_version")
}

Creating client

Next you can create a client as here:

val client = HttpClient(CIO)

where CIO is engine class here. If you confused which engine class you should use consider using CIO.

If you’re using multiplatform, you can omit the engine:

val client = HttpClient()

Ktor will choose an engine among the ones that are available from the included artifacts using a ServiceLoader on the JVM, or similar approach in the other platforms. If there are multiple engines in the dependencies Ktor chooses first in alphabetical order of engine name.

It’s safe to create multiple instance of client or use the same client for multiple requests.

Releasing resources

Ktor client is holding resources: prepared threads, coroutines and connections. After you finish working with the client, you may wish to release it by calling close:

client.close()

If you want to use a client to make only one request consider use-ing it. The client will be automatically closed once the passed block has been executed:

val status = HttpClient().use { client ->
    ...
}

The method close signals to stop executing new requests. It wouldn’t block and allows all current requests to finish successfully and release resources. You can also wait for closing with the join method or halt any activity using the cancel method. For example:

try {
    // Close and wait for 3 seconds.
    withTimeout(3000) {
        client.close()
        client.join()
    }
} catch (timeout: TimeoutCancellationException) {
    // Cancel after timeout
    client.cancel()
}

Ktor HttpClient follows CoroutineScope lifecycle. Check out Coroutines guide to learn more.

Client configuration

To configure the client you can pass additional functional parameter to client constructor. The client configured with HttpClientEngineConfig.

For example, you can limit threadCount or setup proxy:

val client = HttpClient(CIO) {
    threadCount = 2
}

You also can configure an engine using the engine method in a block:

val client = HttpClient(CIO) {
    engine {
        // engine configuration
    }
}

See Engines section for additional details.

Proceed to Preparing the request.