Introducing Ktorfit

Posted on April 15, 2022  •  2 minutes  • 421 words

I released a first version of Ktorfit: a HTTP client / Kotlin Symbol Processor for Kotlin Multiplatform (Js, Jvm, Android, Native, iOS) using KSP and Ktor clients inspired by Retrofit. Find more details here

How to use

For more documentation check: http://foso.github.io/Ktorfit

First do the Setup

Let’s say you want to make a GET Request to https://swapi.dev/api/people/1/

Create a new Kotlin interface

interface ExampleApi {
    @GET("people/1/")
    suspend fun getPerson(): String
}

Now we add a function that will be used to make our request. The @GET annotation will tell Ktorfit that this a GET request. The value of @GET is the relative URL path that will be appended to the base url which we set later.

An interface used for Ktorfit needs to have a Http method annotation on every function. Because Ktor relies on Coroutines by default your functions need to have the suspend modifier. Alternatively you can use #Flow or Call

val ktorfit = Ktorfit.Builder().baseUrl("https://swapi.dev/api/").build()
val exampleApi = ktorfit.create<ExampleApi>()

Next we need to create a Ktorfit object, in the constructor we set the base url. We can then use the create() function to receive an implementation of the wanted type.

val response = exampleApi.getPerson()
println(response)

Now we can use exampleApi to make the request.

Setup

(You can also look how it’s done in the examples )

For Kotlin Native Targets (iOS,Linux) you need to enable the new memory model in gradle.properties

kotlin.native.binary.memoryModel=experimental

KSP

When you are not using KSP already you need to apply the plugin in your build.gradle

plugins {
  id("com.google.devtools.ksp") version "1.7.0-1.0.6"
}

Next you have to add the Ktorfit KSP Plugin to the common target and every compilation target, where you want to use Ktorfit.

val ktorfitVersion = "1.0.0-beta12"

dependencies {
    add("kspCommonMainMetadata", "de.jensklingenberg.ktorfit:ktorfit-ksp:$ktorfitVersion")
    add("ksp[NAMEOFPLATFORM]","de.jensklingenberg.ktorfit:ktorfit-ksp:$ktorfitVersion")
        ...
}

[NAMEOFPLATFORM] is the name of the compilation target. When you want to use it for the Android module it’s kspAndroid, for Js it’s kspJs, etc. Look here for more information https://kotlinlang.org/docs/ksp-multiplatform.html

Ktorfit-lib

Add the Ktorfit-lib to your common module.

val ktorfitVersion = "1.0.0-beta12"

sourceSets {
    val commonMain by getting{
        dependencies{
            implementation("de.jensklingenberg.ktorfit:ktorfit-lib:$ktorfitVersion")
        }
    }

Ktor

Ktorfit is based on Ktor Clients 2.1.0. You don’t need to add an extra dependency for the default clients. When you want to use Ktor plugins for things like serialization, you need to add the dependencies and they need to be compatible with 2.1.0

📙 Documentation

This is only a basic example, for more documentation check: http://foso.github.io/Ktorfit

📜 License

This project is licensed under the Apache License, Version 2.0 - see the LICENSE.md file for details