MENU


Defining an API with Retrofit

Retrofit 43,944 (github.com/square/retrofit (https://github.com/square/retrofit 43,944 ), Apache 2.0) turns an annotated Kotlin interface into an HTTP client. Version 3.0.0 (May 2025) is binary-compatible with 2.x and ships the kotlinx.serialization 5,947 converter as a first-party artifact. Each function is one endpoint, and suspend functions run on OkHttp 47,077 's threads, so you can call them from the main thread:

data/remote/BookApi.kt: BookNest's REST API as an interface (excerpt)Kotlin
interface BookApi {
  @GET("books")
  suspend fun books(): List<BookDto>
  @GET("books/{id}")
  suspend fun book(@Path("id") id: Int): BookDto
}

@Path fills a URL segment, @Query adds a parameter and @Body sends JSON. Retrofit implements the interface with a dynamic proxy, and the converter decodes BookDtos. Hilt provides one instance:

di/NetworkModule.kt: building the Retrofit service (excerpt)Kotlin
  fun provideBookApi(client: OkHttpClient, json: Json): BookApi = Retrofit.Builder()
    .baseUrl(BASE_URL)
    .client(client)
    .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
    .build()
    .create(BookApi::class.java)

The base URL must end with /, and annotation paths must not start with one, or they replace the base path.