Most Kotlin SDKs for API gateways are lazy. They wrap a blocking HTTP client and slap a coroutine adapter on top, hoping you don't notice the friction. nRouter is doing it right with its new Kotlin SDK, version 3.1.2, which treats coroutines as the primary citizen rather than an afterthought. The library, published to the local Maven cache via Gradle, delivers suspend functions for calls and a cold Flow for streaming, eliminating the mental overhead of managing thread pools manually.
Native Async Architecture
The setup is straightforward: implementation("ai.nrouter:nrouter-sdk-kotlin:3.1.2") in your Gradle dependencies. The NRouter() client automatically reads NROUTER_API_KEY from the environment and dispatches operations on Dispatchers.IO. This ensures that network calls never block your caller's context, a critical feature for responsive Android apps and high-throughput Ktor handlers. Unlike typical wrappers, the routing logic itself is embedded in the payload, using "nrouter/auto" and optimization flags like "balanced" or "cost", keeping the client lightweight while offloading complexity to the gateway.
Streaming and Metadata Handling
Streaming responses are implemented as a cold Flow, meaning no network activity occurs until you explicitly call collect. This lifecycle-aware behavior is exactly what you need when integrating with ViewModels or server-side handlers, as the request stops cleanly when the collector goes away. Furthermore, the SDK exposes gateway metadata as typed fields rather than raw headers. You get requestId and cost details directly from result.meta, extracted from x-nr-* headers, so you aren't parsing strings just to track spend or debug issues.
Typed Error Management
Error handling is where many SDKs fall apart, but nRouter provides a robust hierarchy of NRouterError subclasses. You can branch on specific conditions like RateLimit (429), GuardrailBlocked (400), or Service (503). The standout feature is the isRetryable property, which returns true for transient failures like rate limits and transport errors. This simplifies retry logic into a single conditional check, replacing fragile, hand-maintained status code tables.
Key Takeaways
- The nRouter Kotlin SDK v3.1.2 is coroutines-first, using suspend functions and cold Flows natively instead of wrapping blocking clients.
- Routing preferences like
"nrouter/auto"and optimization flags ("balanced","cost") are passed directly in the request payload. - Response metadata, including request IDs and costs, is exposed via typed
result.metafields derived fromx-nr-*headers, avoiding manual string parsing. - A typed error hierarchy with an
isRetryableproperty simplifies retry logic for transient failures like rate limits and service errors.
The Bottom Line
If you're building on the JVM, stop fighting blocking clients. nRouter's coroutines-first approach is the standard we should expect from modern API SDKs.