Skip to main content

Overview

The Kolibrium API module is a code generation tool that uses Kotlin Symbol Processing (KSP) to automatically generate type-safe HTTP client code from annotated request models. It provides a declarative way to define REST API endpoints and generates:

  • Type-safe client methods — Compile-time safety for API calls
  • Automatic serialization/deserialization — Using kotlinx.serialization
  • Authentication handling — Support for Bearer, Basic, API Key, and Custom auth
  • Test harness functions — Built-in testing utilities
  • Path parameter substitution — Automatic URL construction
  • Query parameter handling — Optional parameters with null safety
  • Request body DSL builders — Fluent API for building requests

Note: Context parameters require Kotlin's context parameters feature to be enabled in your project.

Setup​

If you're starting from scratch​

The easiest way to get started is to create a repository from the kolibrium-api-starter template. It includes all necessary dependencies so that you can start coding immediately.

If you already have an existing project​

1. Add KSP plugin​

Add the KSP plugin and Kotlin serialization to your build.gradle.kts:

plugins {
    kotlin("jvm") version "2.3.10"
    kotlin("plugin.serialization") version "2.3.10"
    id("com.google.devtools.ksp") version "2.3.5"
}

2. Add dependencies​

dependencies {
    // Kolibrium API core
    implementation("dev.kolibrium:kolibrium-api-core:<version>")
    
    // KSP annotations
    implementation("dev.kolibrium:kolibrium-api-ksp-annotations:<version>")
    
    // KSP processor
    ksp("dev.kolibrium:kolibrium-api-ksp-processors:<version>")
    
    // Ktor client (required)
    implementation("io.ktor:ktor-client-core:<ktor-version>")
    implementation("io.ktor:ktor-client-cio:<ktor-version>")
    implementation("io.ktor:ktor-client-content-negotiation:<ktor-version>")
    implementation("io.ktor:ktor-serialization-kotlinx-json:<ktor-version>")

    // Testing libraries, such as JUnit, Kotest, etc.
}