Networking with Retrofit

Reviewed & published by Brayan K

Almost every app talks to a server. Retrofit turns a simple annotated Kotlin interface into a fully working, type-safe HTTP client — and with coroutines, network calls read like ordinary code.

Part of the free Kotlin course at LearnCodingFast — hands-on lessons with worked examples and the output they print, plus practice exercises and a quick quiz.

By the end you'll define an API interface with @GET/@POST and suspend functions, plug in a converter, and meet the Ktor client alternative.

What You'll Learn in This Lesson

• Describing an API as an interface
• @GET, @POST, @Path, @Query
• Why network calls are suspend functions
• Adding a JSON converter
• Building a Retrofit instance
• The Ktor client alternative

1️⃣ Describing the API

You declare endpoints on an interface using annotations. @GET sets the method and path; @Path fills URL placeholders; @Query adds query parameters. Mark calls suspend so they run in a coroutine.

import kotlinx.serialization.Serializable
import retrofit2.http.GET
import retrofit2.http.Path
import retrofit2.http.Query

@Serializable
data class User(val id: Int, val name: String)

// Describe the API as an interface with annotated methods.
interface UserApi {

    // GET https://.../users?page=1
    @GET("users")
    suspend fun listUsers(@Query("page") page: Int): List<User>

    // GET https://.../users/{id}
    @GET("users/{id}")
    suspend fun getUser(@Path("id") id: Int): User
}

The interface is pure description. Retrofit generates the working client from it at runtime.

2️⃣ Building Retrofit and Making a Call

A Retrofit.Builder sets the base URL and a converter (here a kotlinx.serialization Json converter), then create() returns a live implementation.

import kotlinx.serialization.json.Json
import okhttp3.MediaType.Companion.toMediaType
import retrofit2.Retrofit
import retrofit2.converter.kotlinx.serialization.asConverterFactory

suspend fun fetchUser() {
    val json = Json { ignoreUnknownKeys = true }

    val retrofit = Retrofit.Builder()
        .baseUrl("https://example.com/api/")
        // A converter turns HTTP bodies into Kotlin objects.
        .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
        .build()

    // create() returns a working implementation of UserApi.
    val api = retrofit.create(UserApi::class.java)

    // suspend call -> runs off the main thread inside a coroutine.
    val user = api.getUser(1)
    println(user.name)
}

3️⃣ The Ktor Client Alternative

Ktor's HttpClient is a Kotlin-first, multiplatform alternative. It uses suspend functions and a content-negotiation plugin for JSON.

import io.ktor.client.HttpClient
import io.ktor.client.call.body
import io.ktor.client.request.get
import io.ktor.client.engine.cio.CIO
import io.ktor.serialization.kotlinx.json.json
import io.ktor.client.plugins.contentnegotiation.ContentNegotiation
import kotlinx.serialization.Serializable

@Serializable
data class Post(val id: Int, val title: String)

// Ktor client is a multiplatform alternative to Retrofit.
suspend fun fetchPost(): Post {
    val client = HttpClient(CIO) {
        install(ContentNegotiation) { json() }
    }
    // A suspend call that returns the deserialized body.
    return client.get("https://example.com/posts/1").body()
}

Your turn. Replace the TODO, then reason about the URL.

// 🎯 YOUR TURN — replace the TODO then reason about the URL.

import retrofit2.http.GET
import retrofit2.http.Path

interface RepoApi {

    // 1) Map this method to GET repos/{owner}/{name}
    //    👉 replace TODO with: @GET("repos/{owner}/{name}")
    TODO
    suspend fun getRepo(
        @Path("owner") owner: String,
        @Path("name") name: String
    ): String
}

Mini-Challenge: A Search Endpoint

Add a search method with a query parameter and a list return type.

// 🎯 MINI-CHALLENGE: a search endpoint.
//
// 1. In an interface SearchApi, add a suspend method search().
// 2. Map it to @GET("search").
// 3. Add a query parameter: @Query("q") term: String.
// 4. Return List<Result> (assume @Serializable data class Result).
//
// ✅ search("kotlin") should issue: GET search?q=kotlin

interface SearchApi {
    // your code here
}

Common Errors (and the fix)

• Calling off a coroutine — A suspend call must run inside a coroutine, e.g. viewModelScope.launch.
• Missing converter — Without an addConverterFactory, Retrofit can't turn JSON into your objects.
• Path mismatch — A {id} in the URL needs a matching @Path("id") parameter.
• Blocking the main thread — Never run network calls synchronously on the UI thread.

Pro Tips

• 💡 One Retrofit instance: build it once and reuse it across the app.
• 💡 Wrap calls in try/catch: handle IOException and HTTP errors gracefully.
• 💡 Pick per platform: Retrofit is great on Android; Ktor shines when you need multiplatform networking.

📋 Quick Reference — Retrofit

🎉 Lesson Complete!

• ✅ Retrofit turns an annotated interface into a client
• ✅ @GET/@POST, @Path, @Query describe requests
• ✅ suspend calls run off the main thread
• ✅ A converter maps JSON to your data classes
• ✅ Ktor is a multiplatform alternative

Practice quiz

Continue this course

• Previous: Serialization with kotlinx.serialization
• Next: Kotlin Multiplatform Intro — Share code across platforms with expect/actual and commonMain
• Quick reference: Kotlin cheat sheet

Frequently asked questions

Why is a Retrofit API an interface, not a class?

You only declare what the endpoints look like — the path, HTTP method, parameters, and return type — using annotations. Retrofit generates the actual implementation at runtime from that interface via retrofit.create(Api::class.java). This keeps your networking code declarative: you describe the API surface and let the library handle building requests, executing them, and parsing responses.

What do @GET, @POST, @Path, and @Query do?

@GET and @POST set the HTTP method and the endpoint path. @Path("id") substitutes a method argument into a {id} placeholder in the URL, so getUser(5) hits users/5. @Query("page") appends a query string such as ?page=2. For POST bodies you typically add a @Body parameter holding a serializable object. Together they map a Kotlin method to a precise HTTP request.

Why mark the methods as suspend?

Network calls must not block the main thread. Declaring the method suspend lets Retrofit run it asynchronously and resume your coroutine with the result, so the call reads like sequential code while staying off the UI thread. You launch these calls from a coroutine scope — commonly viewModelScope in an Android ViewModel.

How does Retrofit turn JSON into my objects, and what's Ktor?

A converter factory does the conversion. Pairing Retrofit with a kotlinx.serialization Json converter means responses are deserialized straight into your @Serializable data classes and request bodies are serialized for you. Ktor's HttpClient is an alternative, Kotlin-first networking library that works across platforms (Android, iOS, JVM); it uses content-negotiation plugins to do the same JSON conversion.