Ktorfit

v1.0.0-beta11 Documentation

Introduction

Ktorfit is a HTTP client/Kotlin Symbol Processor for Kotlin Multiplatform (Js, Jvm, Android, iOS, Linux) using KSP and Ktor clients inspired by Retrofit

Show some :heart: and star the repo to support the project

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-beta11"

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-beta11"

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

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

👷 Project Structure

• ktorfit-annotations - module with annotations for the Ktorfit

• ktorfit-ksp - module with source for the KSP plugin

• ktorfit-lib - module with source for the Ktorfit lib

• sandbox - experimental test module to try various stuff

• example - contains example projects that use Ktorfit

• docs - contains the source for the github page

✍️ Feedback

Feel free to send feedback on Twitter or file an issue. Feature requests are always welcome.

📜 License

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