HTTP client configuration

By default, the AWS SDK for Kotlin uses an HTTP client based on OkHttp. You can override the HTTP client and its configuration by supplying an explicitly configured client.

Note

By default, each service client uses its own copy of an HTTP client. If you use multiple services in your application, you might want to construct a single HTTP client and share it across all service clients.

Basic configuration

When you configure a service client, you can configure the default engine type. The SDK manages the resulting HTTP client engine and automatically closes it when it is no longer needed.

The following example shows configuration of an HTTP client during the initialization of a DynamoDB client.

Imports

import aws.sdk.kotlin.services.dynamodb.DynamoDbClient
import kotlin.time.Duration.Companion.seconds

Code

DynamoDbClient {
    region = "us-east-2"
    httpClient {
        maxConcurrency = 64u
        connectTimeout = 10.seconds
    }
}.use { ddb ->

    // Perform some actions with Amazon DynamoDB.
}

Specify an HTTP engine type

For more advanced use cases, you can pass an additional parameter to httpClient that specifies the engine type. This way, you can set configuration parameters that are unique to that engine type.

The following example specifies the OkHttpEngine that you can use to configure the maxConcurrencyPerHost property.

Imports

import aws.sdk.kotlin.services.dynamodb.DynamoDbClient
import aws.smithy.kotlin.runtime.http.engine.okhttp.OkHttpEngine

Code

DynamoDbClient {
    region = "us-east-2"
    httpClient(OkHttpEngine) {  // The first parameter specifies the HTTP engine type.
        // The following parameter is generic HTTP configuration available in any engine type.
        maxConcurrency = 64u

            // The following parameter is OkHttp-specific configuration.
        maxConcurrencyPerHost = 32u
    }
}.use { ddb ->

    // Perform some actions with Amazon DynamoDB.
}

The possible values for the engine type are OkHttpEngine and CrtHttpEngine.

To use configuration parameters specific to an HTTP engine, you must add the engine as a compile-time dependency. For the OkHttpEngine, you add the following dependency using Gradle.

implementation("aws.smithy.kotlin:http-client-engine-okhttp:0.28.2 ")

For the CrtHttpEngine, add the following dependency.

implementation("aws.smithy.kotlin:http-client-engine-crt:0.28.2 ")

You can find the most recent version of the dependencies at Maven central.

Use an explicit HTTP client

When you use an explicit HTTP client, you're responsible for its lifetime, including closing when you no longer need it. An HTTP client must live at least as long as any service client that uses it.

The following code example shows code that keeps the HTTP client stays alive while the DynamoDbClient is active. The use function makes sure the HTTP client closes properly.

Imports

import aws.sdk.kotlin.services.dynamodb.DynamoDbClient
import aws.smithy.kotlin.runtime.http.engine.okhttp.OkHttpEngine
import kotlin.time.Duration.Companion.seconds

Code

OkHttpEngine {
    maxConcurrency = 64u
    connectTimeout = 10.seconds
}.use { okHttpClient ->

     DynamoDbClient {
        region = "us-east-2"
        httpClient = okHttpClient
    }.use { ddb ->
        {
            // Perform some actions with Amazon DynamoDB.
        }
    }
}