Retrofit Complete Guide for Android

Retrofit turns an HTTP API into a typed Kotlin interface. Production quality depends less on the annotation syntax and more on timeouts, serialization, error mapping, authentication and testability.

Practical guidance

• Keep DTOs separate from UI models.
• Return domain-friendly results from repositories.
• Use one OkHttpClient with explicit timeouts and reviewed interceptors.
• Never log authorization headers or sensitive response bodies in production.

Working example

interface UserApi {
    @GET("users/{id}")
    suspend fun user(@Path("id") id: Long): UserDto
}

class UserRepository(private val api: UserApi) {
    suspend fun user(id: Long): Result<User> = runCatching {
        api.user(id).toDomain()
    }
}

Common mistakes

• HTTP errors, network failures and serialization failures need different user and logging decisions.
• Retrying every request can duplicate writes.
• An authentication interceptor must avoid recursive refresh loops.

Key takeaway

Treat Retrofit as a transport adapter. Translate transport details into stable application errors at the repository boundary.