Ktor — Key Concepts, Client Library, and Kotlin Multiplatform

What is Ktor?

Ktor is a framework for creating HTTP clients and servers in Kotlin, developed by JetBrains. Unlike traditional libraries, Ktor was designed from the start for multiplatform development and works on all platforms supported by Kotlin.

Ktor uses a middleware handler approach, inspired by the architecture of Kodein and Express.js. Each request passes through a pipeline of handler functions that can modify the request and response. This provides flexibility not available in libraries with rigid annotation-based architecture.

The current version Ktor 3.0 includes support for Kotlin 2.0, the K2 compiler, and a new CIO (Coroutine I/O) engine with improved performance. The library is distributed under the Apache 2.0 license and is available for commercial use without restrictions.

The client side of Ktor is fully built on Kotlin coroutines, providing efficient asynchronous request execution without thread blocking. The server side allows creating HTTP servers with routing, request handling, and WebSocket connections.

Ktor uses a plugin architecture: all additional features — logging, serialization, authentication — are connected through plugins. This makes the library modular and allows connecting only the necessary components, reducing the final application size.

Thanks to a unified API across all platforms, developers don’t need to learn different HTTP clients for iOS and Android. In a multiplatform project, the network layer code is fully shared, and the platform-specific implementation is hidden behind the HttpClient engine. This reduces development time and decreases the number of errors related to platform differences.

Key Features of Ktor

Ktor provides a set of features that make it an attractive choice for modern Kotlin projects, especially multiplatform ones.

Multiplatform Support

Ktor works on JVM, Android, iOS, macOS, Windows, Linux, JavaScript, and Wasm. The same HTTP client code runs on all platforms without changes. This is a key advantage over libraries tied to OkHttp or URLSession.

Asynchronous with Coroutines

Coroutines in Kotlin provide natural asynchronicity without callbacks. Each request is a suspend function that can be called from any coroutine. Ktor supports response streaming via Flow, which is convenient for long connections and WebSocket.

Plugin Architecture

Plugins in Ktor are connected through an install block and configured separately. Main plugins: ContentNegotiation for serialization, Logging for logging, Auth for authentication, and WebSockets for bidirectional communication. Each plugin can be enabled or disabled independently.

Error Handling and Timeouts

Error handling in Ktor is based on exceptions. The ClientRequestException class is thrown for 4xx codes, ServerResponseException for 5xx, and IOException for network failures. Timeouts are configured through the HttpTimeout plugin, which sets the timeout for connection, read, and write. For retry attempts, the Retry plugin is used with settings for the number of attempts and delay.

How Does Ktor Work?

Ktor uses a pipeline architecture where each request passes through a chain of handlers. The client creates an HttpClient configuration with installed plugins, and each call to get or post passes through the plugins in the order they were connected.

HttpClient Architecture

The HttpClient object is created with an engine specific to the platform: CIO for JVM and Android, Darwin for iOS and macOS, OkHttp for Android compatibility, Js for browser. The engine can be explicitly selected or left to automatic choice. Each request returns an HttpResponse containing the response body, headers, and status.

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        json(Json {
            ignoreUnknownKeys = true
        })
    }
}

suspend fun fetchUsers(): List<User> {
    return client.get("https://api.example.com/users").body()
}

Installing and Configuring Ktor

Installation of Ktor is done via Gradle or Maven. For multiplatform projects, dependencies are specified in sourceSets for each target. Ktor is distributed through Maven Central.

Connecting via Gradle

In build.gradle.kts, add the ktor-client-core dependency for common code and an engine for the specific platform. The Ktor version is set via a variable in gradle.properties. Ktor 3.x requires Kotlin 2.0+ and supports the K2 compiler.

val ktorVersion = "3.0.3"

dependencies {
    implementation("io.ktor:ktor-client-core:$ktorVersion")
    implementation("io.ktor:ktor-client-cio:$ktorVersion")
    implementation("io.ktor:ktor-client-content-negotiation:$ktorVersion")
    implementation("io.ktor:ktor-serialization-kotlinx-json:$ktorVersion")
    implementation("io.ktor:ktor-client-logging:$ktorVersion")
}

Configuration for iOS

For iOS, the Darwin engine is used, which wraps native URLSession. In Kotlin Multiplatform, this provides maximum performance and integration with iOS system caching mechanisms. The engine is added as a separate dependency in the iOS sourceSet.

An important feature of Ktor is support for different serialization formats through ContentNegotiation. In addition to JSON, the plugin supports Protobuf, CBOR, XML, and custom formats. For serialization, kotlinx.serialization or Jackson libraries are used, and the developer can switch between them without changing request code.

Ktor Usage Examples

The examples below demonstrate typical scenarios for working with the Ktor client: a basic GET request, sending data, and working with multiplatform code.

GET Request with JSON Deserialization

A simple GET request with automatic deserialization of the response into a data class. Ktor uses the ContentNegotiation plugin with kotlinx.serialization to convert JSON into objects. The code is concise and type-safe.

@Serializable
data class Post(
    val id: Int,
    val title: String,
    val body: String
)

suspend fun getPosts(): List<Post> {
    val response = client.get("https://jsonplaceholder.typicode.com/posts")
    return response.body()
}

POST Request with JSON Body

A POST request in Ktor sends a data class as a JSON body via the post method with contentType and setBody. The ContentNegotiation plugin automatically serializes the object into a JSON string. The response can be processed synchronously or asynchronously.

suspend fun createPost(): Post {
    val newPost = Post(
        id = 0,
        title = "New Post",
        body = "Post Content"
    )
    val response = client.post("https://jsonplaceholder.typicode.com/posts") {
        contentType(ContentType.Application.Json)
        setBody(newPost)
    }
    return response.body()
}

File Upload via Multipart

The submitFormWithBinaryData method in Ktor allows sending files and forms in multipart format. Ktor automatically splits the data into parts and adds headers. To track progress, onUpload is used, which receives the bytes of sent data.

suspend fun uploadFile(fileBytes: ByteArray) {
    client.submitFormWithBinaryData(
        url = "https://api.example.com/upload",
        formData = formData {
            append("file", fileBytes, Headers.build {
                append(HttpHeaders.ContentType, "image/png")
                append(HttpHeaders.ContentDisposition, "filename=\"photo.png\"")
            })
        }
    )
}

Ktor or Retrofit: Which to Choose?

The choice between Ktor and Retrofit depends on the project architecture and multiplatform requirements. Retrofit remains the standard for Android-only projects, while Ktor is the best choice for Kotlin Multiplatform.

Ktor also provides built-in WebSocket and SSE (Server-Sent Events) support, making it convenient for real-time applications. Retrofit does not directly support WebSocket — a separate OkHttp WebSocket library is required. Ktor is also easier to configure for different environments thanks to its plugin system, where each plugin is responsible for one function.

Authentication in Ktor

The Auth plugin in Ktor supports basic authentication, Bearer tokens, Digest, and OAuth2. Authentication configuration is done declaratively: the developer specifies the provider, token source, and scope. Ktor automatically adds authentication headers to requests and can refresh the token when it expires.

If a project uses Kotlin Multiplatform with shared code on iOS and Android, Ktor is the only option that works on both platforms without additional layers. Retrofit is tightly tied to OkHttp and JVM, making it unsuitable for iOS.

For Android-only projects, Retrofit provides a more mature API, a larger number of converters and OkHttp interceptors. Ktor also works in this scenario, but its plugin ecosystem is less extensive. Both libraries support coroutines and provide comparable performance.