Ktor — kernconcepten, clientbibliotheek en Kotlin Multiplatform

Wat is Ktor?

Ktor — is een framework voor het maken van HTTP-clients en servers in de taal Kotlin, ontwikkeld door JetBrains. In tegenstelling tot traditionele bibliotheken is Ktor vanaf het begin ontworpen voor multiplatformontwikkeling en werkt het op alle platforms die door Kotlin worden ondersteund.

Ktor gebruikt een benadering van tussenliggende handlers, geïnspireerd door de architectuur van Kodein en Express.js. Elk verzoek doorloopt een pijplijn van handlerfuncties die het verzoek en het antwoord kunnen wijzigen. Dit biedt flexibiliteit die niet beschikbaar is in bibliotheken met een starre, op annotaties gebaseerde architectuur.

De huidige versie Ktor 3.0 omvat ondersteuning voor Kotlin 2.0, de K2-compiler en een nieuwe CIO (Coroutine I/O)-engine met verbeterde prestaties. De bibliotheek wordt gedistribueerd onder de Apache 2.0-licentie en is zonder beperkingen beschikbaar voor commercieel gebruik.

Het clientgedeelte van Ktor is volledig gebouwd op Kotlin-coroutines, wat zorgt voor efficiënte asynchrone uitvoering van verzoeken zonder threads te blokkeren. Het servergedeelte maakt het mogelijk HTTP-servers te maken met routering, verzoekverwerking en WebSocket-verbindingen.

Ktor gebruikt een plugin architectuur: alle extra functies — logging, serialisatie, authenticatie — worden aangesloten via plugins. Dit maakt de bibliotheek modulair en maakt het mogelijk alleen de benodigde componenten aan te sluiten, waardoor de uiteindelijke applicatie kleiner wordt.

Dankzij de uniforme API op alle platforms hoeft de ontwikkelaar geen verschillende HTTP-clients voor iOS en Android te leren. In een multiplatformproject is de code van de netwerklaag volledig gedeeld en is de platformspecifieke implementatie verborgen achter de HttpClient-engine. Dit verkort de ontwikkeltijd en vermindert het aantal fouten dat verband houdt met platformverschillen.

Belangrijkste functies van Ktor

Ktor biedt een reeks functionaliteiten die het een aantrekkelijke keuze maken voor moderne Kotlin-projecten, vooral multiplatformprojecten.

Multiplatformondersteuning

Ktor werkt op JVM, Android, iOS, macOS, Windows, Linux, JavaScript en Wasm. Dezelfde HTTP-clientcode draait op alle platforms zonder wijzigingen. Dit is een belangrijk voordeel ten opzichte van bibliotheken die gebonden zijn aan OkHttp of URLSession.

Asynchroniciteit op coroutines

Coroutines Kotlin bieden natuurlijke asynchroniciteit zonder callbacks. Elk verzoek is een suspend-functie die vanuit elke coroutine kan worden aangeroepen. Ktor ondersteunt streaming van antwoorden via Flow, wat handig is voor lange verbindingen en WebSocket.

Pluginarchitectuur

Plugins Ktor worden aangesloten via een install-blok en afzonderlijk geconfigureerd. Belangrijkste plugins: ContentNegotiation voor serialisatie, Logging voor logging, Auth voor authenticatie en WebSockets voor bidirectionele communicatie. Elke plugin kan onafhankelijk worden in- of uitgeschakeld.

Foutafhandeling en time-outs

Foutafhandeling in Ktor is gebaseerd op uitzonderingen. De klasse ClientRequestException wordt gegenereerd bij 4xx-codes, ServerResponseException bij 5xx en IOException bij netwerkfouten. Time-outs worden geconfigureerd via de HttpTimeout-plugin, die de wachttijd voor verbinding, lezen en schrijven instelt. Voor herhaalde pogingen wordt de Retry-plugin gebruikt met instellingen voor het aantal pogingen en vertraging.

Hoe werkt Ktor?

Ktor gebruikt een pijplijnarchitectuur waarbij elk verzoek door een keten van handlers gaat. De client maakt een HttpClient-configuratie met geïnstalleerde plugins en elke aanroep van de get- of post-methode doorloopt de plugins in de volgorde waarin ze zijn aangesloten.

HttpClient-architectuur

Het HttpClient-object wordt gemaakt met een platformspecifieke engine: CIO voor JVM en Android, Darwin voor iOS en macOS, OkHttp voor Android-compatibiliteit, Js voor de browser. De engine kan expliciet worden gekozen of de automatische selectie kan worden gebruikt. Elk verzoek retourneert een HttpResponse met de antwoordbody, headers en status.

val client = HttpClient(CIO) {
    install(ContentNegotiation) {
        json(Json {
            ignoreUnknownKeys = true
        })
    }
}

suspend fun fetchUsers(): List<User> {
    return client.get("https://api.example.com/users").body()
}

Installatie en configuratie van Ktor

Installatie Ktor gebeurt via Gradle of Maven. In multiplatformprojecten worden afhankelijkheden gespecificeerd in sourceSets voor elk doel. Ktor wordt gedistribueerd via Maven Central.

Aansluiten via Gradle

Voeg in build.gradle.kts de afhankelijkheid ktor-client-core toe voor gedeelde code en de engine voor het specifieke platform. De Ktor-versie wordt ingesteld via een variabele in gradle.properties. Ktor 3.x vereist Kotlin 2.0+ en ondersteunt de K2-compiler.

val ktorVersion = "3.0.3"

dependencies {
    implementation("io.ktor:ktor-client-core:$ktorVersion")
    implementation("io.ktor:ktor-client-cio:$ktorVersion")
    implementation("io.ktor:ktor-client-content-negotiation:$ktorVersion")
    implementation("io.ktor:ktor-serialization-kotlinx-json:$ktorVersion")
    implementation("io.ktor:ktor-client-logging:$ktorVersion")
}

Configuratie voor iOS

Voor iOS wordt de Darwin-engine gebruikt, die de native URLSession omhult. In Kotlin Multiplatform maakt dit maximale prestaties en integratie met de systeemcachingmechanismen van iOS mogelijk. De engine wordt als een aparte afhankelijkheid toegevoegd in de iOS sourceSet.

Een belangrijke functie van Ktor — ondersteuning voor verschillende serialisatieformaten via ContentNegotiation. Naast JSON ondersteunt de plugin Protobuf, CBOR, XML en aangepaste formaten. Voor serialisatie worden de bibliotheken kotlinx.serialization of Jackson gebruikt en de ontwikkelaar kan ertussen schakelen zonder de verzoekcode te wijzigen.

Voorbeelden van Ktor-gebruik

Voorbeelden hieronder tonen typische scenario's voor het werken met de Ktor-client: een basis-GET-verzoek, gegevens verzenden en werken met multiplatformcode.

GET-verzoek met JSON-deserialisatie

Een eenvoudig GET-verzoek met automatische deserialisatie van het antwoord naar een data-klasse. Ktor gebruikt de plugin ContentNegotiation met kotlinx.serialization voor het converteren van JSON naar objecten. De code is beknopt en typeveilig.

@Serializable
data class Post(
    val id: Int,
    val title: String,
    val body: String
)

suspend fun getPosts(): List<Post> {
    val response = client.get("https://jsonplaceholder.typicode.com/posts")
    return response.body()
}

POST-verzoek met JSON-body

Het POST-verzoek in Ktor stuurt een data-klasse als JSON-body via de post-methode met contentType en setBody. De plugin ContentNegotiation serialiseert automatisch het object naar een JSON-string. Het antwoord kan synchroon of asynchroon worden verwerkt.

suspend fun createPost(): Post {
    val newPost = Post(
        id = 0,
        title = "Nieuwe post",
        body = "Inhoud van de post"
    )
    val response = client.post("https://jsonplaceholder.typicode.com/posts") {
        contentType(ContentType.Application.Json)
        setBody(newPost)
    }
    return response.body()
}

Bestand uploaden via Multipart

De methode submitFormWithBinaryData in Ktor maakt het mogelijk bestanden en formulieren in multipart-formaat te verzenden. Ktor splitst de gegevens automatisch in delen en voegt headers toe. Voor het volgen van de voortgang wordt onUpload gebruikt, dat de bytes van verzonden gegevens ontvangt.

suspend fun uploadFile(fileBytes: ByteArray) {
    client.submitFormWithBinaryData(
        url = "https://api.example.com/upload",
        formData = formData {
            append("file", fileBytes, Headers.build {
                append(HttpHeaders.ContentType, "image/png")
                append(HttpHeaders.ContentDisposition, "filename=\"photo.png\"")
            })
        }
    )
}

Ktor of Retrofit: wat te kiezen?

Keuze tussen Ktor en Retrofit hangt af van de architectuur van het project en de vereisten voor multiplatform. Retrofit blijft de standaard voor Android-only projecten, terwijl Ktor de betere keuze is voor Kotlin Multiplatform.

Ktor biedt ook ingebouwde ondersteuning voor WebSocket en SSE (Server-Sent Events), wat het handig maakt voor realtime toepassingen. Retrofit ondersteunt WebSocket niet direct — hiervoor is een aparte OkHttp WebSocket-bibliotheek nodig. Ktor is ook gemakkelijker te configureren voor verschillende omgevingen dankzij het pluginsysteem, waarbij elke plugin verantwoordelijk is voor één functie.

Authenticatie in Ktor

De Auth-plugin in Ktor ondersteunt basisauthenticatie, Bearer-tokens, Digest en OAuth2. Configuratie van authenticatie gebeurt declaratief: de ontwikkelaar specificeert de provider, tokenbron en het werkingsgebied. Ktor voegt automatisch authenticatie-headers toe aan verzoeken en kan het token vernieuwen wanneer het verloopt.

Als het project Kotlin Multiplatform gebruikt met gedeelde code op iOS en Android, is Ktor de enige optie die op beide platforms werkt zonder extra lagen. Retrofit is sterk gebonden aan OkHttp en JVM, wat het ongeschikt maakt voor iOS.

Voor Android-only projecten biedt Retrofit een volwassenere API, meer converters en OkHttp-interceptors. Ktor werkt ook in dit scenario, maar het pluginecosysteem is minder uitgebreid. Beide bibliotheken ondersteunen coroutines en bieden vergelijkbare prestaties.