android-retrofit

Android Networking with Retrofit

Modern Retrofit setup for Android using coroutines, kotlinx.serialization, and Hilt. This reference covers the decisions that are easy to get wrong, not the standard boilerplate of service interfaces, Hilt module wiring, and the converter setup.

Service interface

Declare every endpoint as a suspend function. Return the body type directly — Retrofit throws HttpException on non-2xx, giving a clean try/catch at the repository boundary. Use Response<T> only when you need the status code, headers, or error body (e.g. server-side validation messages):

// Direct body — throws HttpException on non-2xx; the common case
@GET("users/{user}/repos")
suspend fun listRepos(@Path("user") user: String): List<Repo>

// Response wrapper — only when you need code/headers/error body
@GET("users/{user}")
suspend fun getUser(@Path("user") user: String): Response<User>

Wrapping every endpoint in Response<T> "just in case" forces callers to check isSuccessful and handle a nullable body even when only the body matters — don't.

OkHttp & JSON

Standard wiring (in a Hilt @Module/@Provides @Singleton): HttpLoggingInterceptor with its level gated on BuildConfig.DEBUG, sensible connect/read timeouts, and the kotlinx.serialization converter (json.asConverterFactory("application/json".toMediaType())). For an API that's loose with its payloads, configure:

Json { ignoreUnknownKeys = true; coerceInputValues = true; isLenient = true }

Auth: interceptor, and the throw-vs-proceed decision

Attach the token via an Interceptor, not a per-endpoint @Header — a single missed @Header parameter is an unauthenticated request that fails at runtime, not compile time. The part most often gotten wrong is what to do when the token is absent:

class AuthInterceptor @Inject constructor(
    private val tokenProvider: TokenProvider,
) : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val token = tokenProvider.getToken()
            ?: throw IOException("Auth token unavailable") // fail fast — see note below
        val request = chain.request().newBuilder()
            .header("Authorization", "Bearer $token")
            .build()
        return chain.proceed(request)
    }
}