DEV Community

nRouter
nRouter

Posted on

A gateway SDK that refuses to be a new API: notes on nRouter's Java SDK

Most vendor SDKs ask you to learn a second API and call it convenience. nRouter's Java SDK page makes the opposite bet, and it's worth a look for exactly that reason: there is almost no new API to learn.

One dependency, one static factory, the client you already know

The SDK ships on Maven Central as ai.nrouter:nrouter-sdk:3.1.2 — one line in a pom.xml, or implementation 'ai.nrouter:nrouter-sdk:3.1.2' in Gradle. Then:

OpenAIClient client = NRouter.create();

That's the whole integration surface of the nRouter-specific code. NRouter.create() reads NROUTER_API_KEY from the environment, targets https://api.nrouter.ai/v1, and hands you back a configured instance of the standard OpenAI Java client. Everything after that — client.chat().completions().create(...), the builder-typed ChatCompletionCreateParams, the response types — is the OpenAI Java API, unchanged. The page calls this "full OpenAI API parity", and the examples back it up: if your team already writes against the OpenAI Java client, the gateway arrives as a dependency and a line of setup, not a rewrite.

Builders, Optionals, thread safety

The examples are idiomatic modern Java. Requests are built with the typed builder — .model(...), .addMessage(ChatCompletionMessageParam.ofUser(...)) — and message content comes back as an Optional you unwrap with orElse. The bindings are described as thread-safe, which matters for the way Java services actually run: one client, shared across request threads, no per-call construction cost and no synchronization folklore in your codebase.

Streaming is a stream

Token streaming uses createStreaming(params), and the chunks arrive as a Java Stream you consume with forEach — each chunk's delta content is an Optional printed if present. SSE underneath, ordinary stream operations on top. Anyone who has wired a reactive pipeline by hand for a chat endpoint will appreciate how little machinery is on the page.

Errors are an exception ladder, not a status code hunt

Failures surface as the OpenAI Java exception types, and the guide's example catches them in order: BadRequestException (which it labels as covering a guardrail violation), AuthenticationException for a bad key, RateLimitException with the obvious advice to back off, and the base OpenAIException for everything else from the gateway. Typed catches beat parsing error JSON in a catch-all, especially in services where a rate limit and an auth failure page different people.

The honest summary: this SDK's feature is restraint. It configures the client you already know for a gateway endpoint and gets out of the way — the guide is at https://nrouter.ai/docs/sdks/java if you want to check the claim against the code.

Disclosure: I'm with the nRouter team.

Top comments (0)