DEV Community

nRouter
nRouter

Posted on

Coroutines first: notes on nRouter's Kotlin SDK

A Kotlin client for an API gateway can be a thin wrapper around blocking HTTP calls, with a coroutine adapter bolted on. The nRouter Kotlin guide goes the other way: the SDK is coroutines-first from the start — suspend functions for calls, a cold Flow for streaming, and typed error subclasses you can branch on.

Full guide: https://nrouter.ai/docs/sdks/kotlin

Setup

The guide publishes the artifact to your local Maven cache (./gradlew clean check publishToMavenLocal), then it's a normal Gradle dependency:

dependencies {
    implementation("ai.nrouter:nrouter-sdk-kotlin:3.1.2")
}
Enter fullscreen mode Exit fullscreen mode

NRouter() reads NROUTER_API_KEY from the environment, targets https://api.nrouter.ai/v1, and dispatches on Dispatchers.IO, so calls don't block your caller's context. (For Android apps, the guide points to the separate nrouter-sdk-android artifact.)

A call, and what comes back

suspend fun main() {
    val client = NRouter()

    val result = client.chatCompletions(
        JSONObject()
            .put("model", "nrouter/auto")
            .put("messages", listOf(mapOf("role" to "user", "content" to "Hello!")))
            .put("nrouter_optimize", "balanced")
    )

    val content = result.body.getJSONArray("choices")
        .getJSONObject(0).getJSONObject("message").getString("content")
    println(content)
    println("Request ID: ${result.meta.requestId}")
}
Enter fullscreen mode Exit fullscreen mode

Two things worth noticing. The routing preference rides in the payload: "nrouter/auto" plus "nrouter_optimize" (quality, balanced or cost), with "nrouter_cost_band" (low, mid, high) available under cost. And the response carries .meta extracted from the gateway's x-nr-* headers, so request ID and cost metadata arrive as typed fields instead of header strings you parse yourself.

Streaming is a cold Flow — nothing moves until you collect:

client.messagesStream(
    JSONObject()
        .put("model", "nrouter/auto")
        .put("messages", listOf(mapOf("role" to "user", "content" to "Hello!")))
).collect { chunk ->
    print(chunk.delta)
}
Enter fullscreen mode Exit fullscreen mode

Cold matters here: the request starts on collection and stops when the collector goes away, which is exactly the lifecycle behaviour you want in a view model or a Ktor handler.

Errors you can branch on

Gateway refusals map to subclasses of NRouterError: Request (400, including cost_band_unsatisfiable), GuardrailBlocked (400), Authentication (401), Credit (402), RateLimit (429) and Service (503). The detail that makes this practical is isRetryable — true for RateLimit, Service and Transport — so a retry policy is one when branch instead of a table of status codes maintained by hand.

That's the whole shape: a JVM client that treats coroutines as the default rather than an add-on, and lets the gateway carry routing, budgets and guardrails behind one key. The guide has the full walkthrough: https://nrouter.ai/docs/sdks/kotlin

Top comments (0)