Networking with the Ktor Client

Ktor is built from the ground up on Kotlin coroutines and Kotlin Multiplatform, so a request is a suspend call that works unchanged on every target.

The trade-off is where the boundary sits: if the shared module owns networking, one client enforces the same authentication, retry and error semantics on every platform, at the cost of iOS developers no longer seeing requests in Swift tooling (Ktor’s logging plugin compensates). See Architecture, Shared ViewModels and State.

An HttpClient has two parts: the client core with its plugins (JSON, auth, retries), which is pure common Kotlin, and an engine that performs the actual I/O. The core artifact ktor-client-core goes in commonMain; engine artifacts go in platform source sets. When you call HttpClient() without an argument in common code, Ktor picks the engine found on the classpath of that target, which is why one engine dependency per target is enough.

On Apple targets prefer ktor-client-darwin, because it integrates with system-level behaviour such as VPN, proxy settings and certificate trust that a pure-Kotlin engine would bypass. ktor-client-cio is the pure-Kotlin alternative on Android and JVM (no HTTP/2) and also runs on Linux and Windows native targets, and ktor-client-curl is the alternative on Linux and Windows desktop.

An HttpClient is heavyweight: it owns a connection pool and threads. Create one per app and reuse it, closing it only when the app shuts down. Creating a client per request is the most common performance bug.

Each plugin is explained in the sections below. See Ktor — Create and configure a client.

ContentNegotiation converts request bodies to JSON and response bodies back to Kotlin objects. It needs a serializer; on KMP that is ktor-serialization-kotlinx-json, which depends on kotlinx.serialization and works on every target (Gson and Jackson do not, because they are JVM-only). The model classes carry @Serializable, which is generated by the compiler plugin org.jetbrains.kotlin.plugin.serialization.

DTOs (data transfer objects) are kept separate from the domain Trail so that a server rename never ripples into the UI. ignoreUnknownKeys = true keeps old app versions working when the server adds fields, a property that matters because mobile users update slowly. See Ktor — Content negotiation and serialization in the client and Kotlin docs — Serialization.

The API client is a plain class that takes the HttpClient through its constructor. This dependency injection (DI) keeps it testable and lets Koin supply the shared client.

Three details are worth noticing. The relative path "trails" is resolved against the defaultRequest base URL https://api.example.com/v1/ (the trailing slash matters, because without it /v1 is dropped; it makes the resolution append rather than replace the last segment). parameter() URL-encodes values, so never concatenate query strings by hand. And .body() is a reified function that deserializes using the installed ContentNegotiation. See Ktor — Making requests and Ktor — Receiving responses.

defaultRequest { } applies settings to every request the client makes: the base URL, shared headers and the content type. It removes repeated boilerplate and gives one place to change the API host between environments.

The block above already sets the base URL and Content-Type; shared headers such as header("X-Client", "trailmate-kmp") and Accept-Language go in the same block, and url { protocol = URLProtocol.HTTPS; host = "api.example.com" } is the structured alternative to a string URL.

A request can still override any default (for instance to call a different host for an image CDN). If the base URL comes from build configuration, pass it into HttpClientFactory.create(baseUrl, engine) rather than reading globals. See Ktor — Default request.

Without HttpTimeout, behaviour depends on each engine’s defaults, which differ between OkHttp, NSURLSession and fetch. Installing the plugin gives one consistent policy.

The plugin has three limits: connectTimeoutMillis (establishing the connection, typically 10 s), requestTimeoutMillis (the whole call, typically 30 s) and socketTimeoutMillis (maximum silence between packets, typically 30 s).

A timeout throws HttpRequestTimeoutException, ConnectTimeoutException or SocketTimeoutException. The plugin is Stable on all targets, but note that on the Js engine the connect and socket timeouts are not supported by the browser fetch API, so only requestTimeoutMillis applies there. Timeouts can also be set for a single request with timeout { requestTimeoutMillis = 120_000 }, which is the right tool for large downloads. See Ktor — Timeout.

HttpRequestRetry re-sends requests that failed because of a server error or an exception. Retrying blindly is dangerous (a repeated POST can create duplicates), so decide per request.

exponentialDelay waits longer after each failure, with jitter, so many clients do not retry in lockstep against a recovering server. A single request opts out with retry { noRetry() }. Retries multiply the total wall-clock time, so size requestTimeoutMillis accordingly or the caller waits minutes before seeing an error. See Ktor — Retrying failed requests.

The Logging plugin prints requests and responses. Logger.SIMPLE prints to the platform’s standard output, which on iOS shows up in the Xcode console. A custom Logger forwards lines to a logging library such as Kermit.

A custom logger is logger = object : Logger { override fun log(message: String) = AppLog.d("Http", message) }, and sanitizeHeader { it == HttpHeaders.Authorization } redacts the token from the output.

Levels run from ALL to NONE. Never log bodies or tokens in release builds; use sanitizeHeader to redact Authorization. See Ktor — Logging.

The Auth plugin with the bearer provider adds an Authorization: Bearer <token> header and, when the server answers 401 Unauthorized, calls refreshTokens once and replays the request. This logic is identical on every platform, which is a strong argument to keep it in common code.

markAsRefreshTokenRequest() tells the plugin that this call must not itself trigger a refresh, which avoids an infinite loop. sendWithoutRequest limits the header to your own host, so the token is not leaked to third-party URLs such as image CDNs. Store tokens in the platform keystore (Android Keystore, iOS Keychain) behind TokenStore, never in plain preferences; the tokens in this snippet are placeholders supplied at runtime. Ktor caches the loaded tokens in memory until a refresh happens, so call the clearToken() extension of the provider on logout. See Ktor — Bearer authentication.

By default Ktor does not throw for 4xx and 5xx responses; client.get(…​) returns a response and .body() fails later with a confusing deserialization error. Setting expectSuccess = true turns non-2xx statuses into exceptions:

The exceptions are RedirectResponseException (3xx), ClientRequestException (4xx), ServerResponseException (5xx), all subclasses of ResponseException, plus HttpRequestTimeoutException and platform-specific I/O errors for a network that is down.

Because engine exceptions differ per platform, wrap them in your own sealed error type at the data boundary so that the ViewModel handles one hierarchy.

Rethrowing CancellationException is essential: swallowing it breaks structured concurrency, so a cancelled screen would keep running work. For server-defined error bodies, install a HttpResponseValidator { handleResponseExceptionWithRequest { …​ } } that reads the JSON error payload once for the whole client. See Ktor — Response validation.

For real-time features such as live trail conditions, Ktor provides a WebSocket client. Install the plugin and open a session; frames arrive as a coroutine-friendly stream.

This requires install(WebSockets) and the ktor-client-websockets artifact. Support varies by engine: OkHttp, Darwin, CIO, Java and Js support it, but the Darwin engine exposes WebSockets through NSURLSession and does not accept every extension. Server-Sent Events (SSE) is a simpler alternative for one-way streams. See Ktor — WebSockets in the client.

Because the engine is injected, tests replace it with MockEngine, which answers from a lambda without any network. This is also how FakeTrailApiClient is built. Tests run in commonTest, so the same suite executes on JVM, iOS simulator and the other targets.

Using the real HttpClientFactory with a MockEngine tests the configured client (serialization, base URL, expectSuccess) and not just your code. The mock engine is Stable and is the recommended approach; Mokkery-style mocks of HttpClient are fragile because HttpClient is a large concrete class. See Ktor — Testing and Testing Multiplatform Code.

The client is a Koin singleton, single { HttpClientFactory.create(httpClientEngine()) }, and TrailApiClient is bound to TrailApi with single<TrailApi> { TrailApiClient(get()) } inside trailMateModule; see Dependency Injection in KMP: Koin, Metro and Manual DI and Koin — Koin for Kotlin Multiplatform.

The iOS app never touches Ktor directly; it calls the repository or observes the shared ViewModel. A suspend function exported to Swift becomes async throws with SKIE, and a completion-handler function without it.

Without SKIE a suspend function must be annotated with @Throws(CancellationException::class) or an uncaught Kotlin exception terminates the iOS process. See Consuming Coroutines and Flow from Swift and SwiftUI and Objective-C Interop, Swift Export and SKIE. See SKIE — Swift Kotlin Interface Enhancer.

On Android declare android.permission.INTERNET in the app manifest (androidApp) and remember that cleartext HTTP is blocked by default. On iOS, App Transport Security requires HTTPS. In the browser the API must send CORS headers for your origin. Desktop has no permission model.

Older tutorials, including many from the Kotlin Multiplatform Mobile era, use Ktor 1.x. The code does not compile on Ktor 3.x; these are the changes you will meet.

Migrate by first replacing JsonFeature and the artifact names, then fix imports from features to plugins, then change get<T>() calls to .body<T>(). Ktor 3.0 additionally changed engine configuration types and removed several deprecated APIs from 2.x; the official migration guides list each. See Ktor — Migrating from 1.x to 2.x and Ktor — Migrating from 2.x to 3.x.