Ktorfit
v1.0.0-beta04 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
❤️
and star the repo to support the project
Show some
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(baseUrl = "https://swapi.dev/api/")
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.6.20-1.0.4"
}
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-beta04"
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-beta04"
sourceSets {
val commonMain by getting{
dependencies{
implementation("de.jensklingenberg.ktorfit:ktorfit-lib:$ktorfitVersion")
}
}
Ktor
Ktorfit is based on Ktor Clients 2.0.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.0.0
📙
Documentation
In this Readme is only a basic example, for more documentation check: http://foso.github.io/Ktorfit
👷
Project Structure
-
ktorfit-ksp - module with source for the KSP plugin
-
ktorfit-lib - module with source for the Ktorfit lib
-
workload - 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