Ktorfit

Ktorfit is an HTTP client using KSP and Ktor clients.

Introduction
Project
Quick start
Requests
Todo

Introduction

Ktorfit uses Kotlin Symbol Processing to generate type-safe HTTP client implementations based on annotated interfaces. It leverages Ktor - Client‘s powerful and flexible HTTP capabilities, making it easy to perform network operations in Kotlin applications.

Project

Create a new Kotlin project with Amper.

Update the module.yaml file to add the Ktorfit dependencies:

module.yaml

dependencies:
  - de.jensklingenberg.ktorfit:ktorfit-lib-light:2.6.4
  - io.ktor:ktor-client-cio:3.3.1
  - io.ktor:ktor-client-content-negotiation:3.3.1
  - io.ktor:ktor-serialization-kotlinx-json:3.3.1
settings:
  kotlin:
    ksp:
      processors:
        - de.jensklingenberg.ktorfit:ktorfit-ksp:2.6.4

You need to add ktorfit-kspfor KSP.

de.jensklingenberg.ktorfit:ktorfit-lib-light only add the Ktor client core dependency and not the platform dependencies for the clients (this gives you more control over the used clients).

When you want to use Ktor plugins for things like serialization, you need to add the dependencies.

Quick start

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

Create a new Kotlin interface (it has to be defined inside a package, for example api):

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

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 an HTTP method annotation on every function. Because Ktor relies on Coroutines by default, your functions need to have the suspend modifier.

Nota

The return type String will return the response text. When you want directly parse the response into a class you need to add a JSON,XML, etc. converter to Ktor

Next we use the Ktorfit builder to create a Ktorfit instance and set the base url.

After compiling the project, we can then use the generated extension function createStarWars to receive an implementation of the wanted type.

fun build(): StarWars {
    val ktorfit = Ktorfit.Builder().baseUrl("https://swapi.dev/api/").build()
    return ktorfit.createStarWars()
}

Now you can use StarWars API to make the request.

suspend fun main() {

    val api = api.build()
    val response = api.getPerson()
    println(response)
}

Requests

Ktorfit supports the following the HTTP method annotations: @GET, @POST, @PUT, @DELETE, @HEAD, @OPTIONS, and @PATCH.

JSON

Ktorfit doesn’t parse JSON. You have to install the JSON Feature to the Ktor Client that you add to Ktorfit.

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

val ktorfit = Ktorfit.Builder().httpClient(client).baseUrl("https://swapi.dev/api/").build()

Path

When you want to dynamically replace a part of the URL, you can use the @Path annotation.

interface ExampleApi {
    @GET("people/{id}/")
    suspend fun getPerson(@Path("id") id: Int): Person
}

Just write a part of your URL path in curly braces. Then you need to annotate a parameter with @Path. The value of @Path needs to match with one of the curly braces part in your URL path.

Example:

On a request with getPerson(1) , {peopleId} will be replaced with argument 1 and the relative URL will become people/1/

Kotlin - Ktorfit