Kotlin

The Kotlin SDK publishes to Maven Central and is the only language besides TypeScript with an HTTP engine choice. It is a JVM library, built with a Java 21 toolchain, and serialises models with Jackson.

Install

implementation 'com.your-org:api-client-kotlin:1.0.0'

Options

Set these for Kotlin in SDK Studio. Each one names its key for octri sdk settings set. Every option, for every language, is in the settings reference.

HTTP enginechoicedefault: okhttp

okhttp or ktor. See HTTP engine.

httpEngine.kotlin

SDK typechoicedefault: disabled

Value	Studio label	Methods
`disabled`	Blocking	Block until the response arrives
`enabled`	Coroutines	Are `suspend` functions

outputByLang.kotlin.coroutines

Client stylechoicedefault: class

class gives callers a client to create. functions gives free functions to import. See client style.

clientStyleByLang.kotlin

Namespacechoicedefault: tags

Groups operations by tags, by URL path, or not at all with none.

namespaceByLang.kotlin

Method namingchoicedefault: short

short drops the group's word from the method name, and full keeps the operation ID. Set for every language at once.

methodNaming

Argument stylechoicedefault: positional

object takes one parameters object, and positional takes arguments in order. See argument style.

outputByLang.kotlin.argumentStyle

Doc commentschoicedefault: full

full or minimal.

outputByLang.kotlin.docComments

Usage examplechoicedefault: full

full or concise.

outputByLang.kotlin.usageExample

File headerchoicedefault: include

include or omit. Omitting it needs the Enterprise plan. Set for every language at once.

fileHeader

HTTP engine

// Operations are plain blocking calls.
val invoice = acme.invoices.create(customerId = "cus_123", amountCents = 4900)

The default. OkHttp is already on the classpath of most Android apps and JVM services, so it usually adds nothing new to a consumer's build.

Ktor if your users write coroutines

Choose ktor when your consumers call the SDK from coroutines and want suspend functions. With OkHttp, turning on Coroutines in SDK Studio also generates suspend functions.

Both engines target the JVM

Either engine produces a JVM library, because the models serialise through Jackson, so the SDK does not build for Kotlin/Native or Kotlin/JS.

Package name

Same Maven coordinates as Java, and the same groupId ownership requirement:

com.acme:api-client-kotlin

Kotlin and Java both publish to Maven Central, so give them distinct artifactIds. Set Package name per language for Kotlin, so it does not inherit the project-wide name Java uses.

What callers write

import acmeapi.*

val acme = Acme(ClientConfig(
    baseUrl = "https://api.acme.com/v1",
    auth = ClientAuthConfig(bearer = System.getenv("ACME_TOKEN")),
))

// The trailing lambda gets each item. Return false to stop paging.
acme.users.listPaginated(limit = 100) { user ->
    println(user.id)
    true
}

Optional parameters are default arguments, and models are data classes. SdkError is a sealed class, and each common status is a subclass of SdkHttpError (SdkNotFoundError, SdkRateLimitError and so on) carrying statusCode and requestId.

Runtime


Requires	A Java 21 toolchain
HTTP	OkHttp, or Ktor if you choose it
Timeout	30 seconds per attempt
Retries	Up to 3 attempts, with backoff from 500 ms to 8 seconds
Idempotency keys	`POST` and `PATCH`

Those are the defaults. See every setting and retries and timeouts to change them.

Streaming

For an operation that streams:

client.events.stream().forEach { event ->
    println(event.id)
}

Returns a Sequence with OkHttp, or a Flow with Ktor. See streaming.

Handling errors

try {
    client.users.get(id = "usr_1")
} catch (error: SdkNotFoundError) {
    return null
} catch (error: SdkHttpError) {
    println("${error.statusCode} ${error.requestId}")
    throw error
}

Each common status has its own subclass of SdkHttpError. error.data holds the decoded model, which you can narrow with is. See what's in the package.

Java

The other Maven Central language.

Publishing

Connect Maven Central and release.