Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 38 ยท Deployment and Coroutines

The Ktor HTTP Client - Calling Other Services

Use the Ktor HTTP client from a server: engines, JSON bodies, timeouts, retries with backoff, error handling, parallel calls and swapping in a fake engine for fast, offline tests.

Most servers call other servers: a payment API, a weather service, another team's microservice. Ktor ships a coroutine-based HTTP client that shares its design with the server: the same plugins idea, the same ContentNegotiation, and suspend functions all the way. This lesson shows how to create one client for your whole application, send requests, parse JSON, protect yourself with timeouts and retries, and test code that uses the client without any network.

About the examples. The client code is real Ktor and read-only here (no Ktor jars on the runner). Runnable blocks are stand-ins in plain Kotlin: a fake engine, a retry loop with backoff, and parallel calls. They model the ideas, not the library.

Dependencies and creating a client

Kotlin
// build.gradle.kts
implementation("io.ktor:ktor-client-core:3.4.0")
implementation("io.ktor:ktor-client-cio:3.4.0")                     // the engine
implementation("io.ktor:ktor-client-content-negotiation:3.4.0")
implementation("io.ktor:ktor-serialization-kotlinx-json:3.4.0")
testImplementation("io.ktor:ktor-client-mock:3.4.0")

The client has a pluggable engine that does the real network I/O: CIO (pure Kotlin, a good default), Java, Apache5, OkHttp (popular on Android) or Darwin and others for multiplatform. Everything else is configuration:

Kotlin
val client = HttpClient(CIO) {
    install(ContentNegotiation) { json(Json { ignoreUnknownKeys = true }) }
    install(HttpTimeout) {
        connectTimeoutMillis = 2_000
        requestTimeoutMillis = 5_000
    }
    defaultRequest {
        url("https://api.example.com/v1/")
        header("Accept", "application/json")
    }
}

Create one client and reuse it. A client holds connection pools and threads; making a new one per request is slow and leaks resources. Close it when the application stops:

Kotlin
monitor.subscribe(ApplicationStopped) { client.close() }

Making requests

Kotlin
@Serializable data class Weather(val city: String, val tempC: Double)

suspend fun fetchWeather(city: String): Weather =
    client.get("weather") { parameter("city", city) }.body()

suspend fun createOrder(order: NewOrder): Order =
    client.post("orders") {
        contentType(ContentType.Application.Json)
        setBody(order)
        bearerAuth(token)
    }.body()

get, post, put, delete and friends return an HttpResponse. Call .body<T>() to decode it (needs ContentNegotiation), or .bodyAsText() for the raw string. You can read response.status, response.headers and so on. Because these are suspend functions, calling them inside a route handler does not block the engine thread.

Status codes and errors

By default the client does not throw for 4xx and 5xx responses; it returns them. Either check the status yourself or ask for exceptions:

Kotlin
val client = HttpClient(CIO) { expectSuccess = true }   // throws ClientRequestException (4xx), ServerResponseException (5xx)
Kotlin
suspend fun loadUser(id: Int): User? = try {
    client.get("users/$id").body()
} catch (e: ClientRequestException) {
    if (e.response.status == HttpStatusCode.NotFound) null else throw e
}

Distinguish three failure types: the server said no (4xx, usually do not retry), the server failed (5xx, may be worth retrying) and the network failed (timeouts, connection reset, retry carefully).

Timeouts

Always set timeouts. A call without one can wait forever and tie up a coroutine, a connection and eventually a thread. The three useful values are: connect (reaching the host), socket (silence while reading), and request (the whole call). Choose them from what your own users can tolerate: if your page must answer in two seconds, a three-second downstream timeout is a bug.

Retries with backoff

Transient failures (a restarted pod, a brief 503) often succeed on a second try. The HttpRequestRetry plugin does this:

Kotlin
install(HttpRequestRetry) {
    retryOnServerErrors(maxRetries = 3)
    retryOnException(maxRetries = 3, retryOnTimeout = true)
    exponentialDelay()          // wait 1s, 2s, 4s ... plus randomness
}

Retries have rules. Retry only idempotent requests (GET, PUT, DELETE) or POSTs that carry an idempotency key; otherwise a retry might charge a card twice. Use exponential backoff with random jitter so a thousand clients do not hammer a recovering service at the same instant. Cap the number of attempts.

Kotlin Stand-in: retry with exponential backoff

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

Parallel calls

Calling several services for one response is where coroutines shine. Run independent requests concurrently and wait for all of them:

Kotlin
get("/summary/{city}") {
    val city = call.parameters["city"]!!
    val (weather, news) = coroutineScope {
        val w = async { weatherClient.fetch(city) }
        val n = async { newsClient.latest(city) }
        w.await() to n.await()
    }
    call.respond(Summary(weather, news))
}

Combine this with timeouts and a fallback: if the news service is slow, return the weather with an empty news list instead of failing the whole page. This is a form of graceful degradation, and users prefer a partial answer to an error.

Kotlin Stand-in: parallel calls with a fallback

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

Testing with MockEngine

Because the engine is pluggable, a test can swap the network for a fake that returns canned responses. No server, no ports, no flakiness:

Kotlin
val mockEngine = MockEngine { request ->
    when (request.url.encodedPath) {
        "/v1/weather" -> respond(
            content = """{"city":"Oslo","tempC":21.0}""",
            status = HttpStatusCode.OK,
            headers = headersOf(HttpHeaders.ContentType, "application/json"),
        )
        else -> respond("", HttpStatusCode.NotFound)
    }
}
val client = HttpClient(mockEngine) {
    install(ContentNegotiation) { json() }
}

Design your code so the client is passed in (a constructor parameter) rather than created inside a function. Then a production module builds a CIO client and a test builds a MockEngine client. This is the same dependency idea as in Testing with Fakes and Databases.

The stand-in below shows the pattern with a tiny interface: the code under test depends on an abstraction of "send a request", and a fake implementation provides canned answers.

Kotlin Stand-in: a fake engine for offline tests

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

Common mistakes

  • Creating a new HttpClient for every request.
  • No timeouts, so a slow partner makes your whole service slow.
  • Retrying non-idempotent POSTs without an idempotency key.
  • Forgetting ignoreUnknownKeys = true, so a harmless new field in someone else's JSON breaks your parsing.
  • Logging request headers that contain tokens.
  • Using blocking client libraries inside handlers instead of the suspend-based Ktor client.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How many HttpClient instances should a typical application create?

    A client owns connection pools, so it is created once and reused.
  2. 2. Which requests are safe to retry automatically?

    Retrying a non-idempotent request can repeat its side effect, such as a double charge.
  3. 3. What is the purpose of jitter in retry backoff?

    Random variation prevents synchronized retry storms against a recovering service.
  4. 4. What does MockEngine let you do?

    It replaces the network engine, so tests are fast and deterministic.

Summary

  • Create one HttpClient with an engine, ContentNegotiation, timeouts and defaults; close it on shutdown.
  • Use suspend calls and .body<T>(); decide how to treat 4xx, 5xx and network errors.
  • Retry only idempotent calls, with capped exponential backoff and jitter.
  • Combine async and withTimeoutOrNull for parallel calls with graceful fallbacks.
  • Inject the client so tests can use MockEngine.

Next: Project: A URL Shortener