OkHttp

What Are Interceptors?

Interceptors are a powerful mechanism to observe, modify, and retry requests. They form a chain: each interceptor processes the request, passes it forward, and can process the response on the way back.

val client = OkHttpClient.Builder()
    .connectTimeout(15, TimeUnit.SECONDS)
    .readTimeout(15, TimeUnit.SECONDS)
    .writeTimeout(15, TimeUnit.SECONDS)
    .addInterceptor(HttpLoggingInterceptor().apply {
        level = HttpLoggingInterceptor.Level.BODY
    })
    .addInterceptor(AuthInterceptor { tokenManager.getToken() })
    .addNetworkInterceptor(CacheInterceptor())
    .build()

Application Interceptors vs Network Interceptors

OkHttp has two interceptor positions:

• Application interceptors: Run before the cache. See the original request. Retries, redirects, and compressions are hidden. Use for logging, auth headers, and request modification.
• Network interceptors: Run after the cache. See the actual request sent over the wire. Use for fine-grained control of headers like Content-Encoding.

class AuthInterceptor(private val tokenProvider: () -> String) : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val token = tokenProvider()
        val request = chain.request().newBuilder()
            .addHeader("Authorization", "Bearer $token")
            .build()
        return chain.proceed(request)
    }
}

Connection Pooling

OkHttp maintains a connection pool to reuse TCP connections. On mobile, this avoids repeated TLS handshakes.

val client = OkHttpClient.Builder()
    .connectionPool(
        ConnectionPool(
            maxIdleConnections = 5,
            keepAliveDuration = 5,
            timeUnit = TimeUnit.MINUTES
        )
    )
    .build()

maxIdleConnections controls how many unused connections to keep alive. Too many wastes memory; too few causes frequent reconnects.

HTTP Caching in OkHttp

OkHttp supports transparent HTTP caching using Cache-Control headers from the server. When configured, cached responses avoid network calls entirely.

val cache = Cache(
    directory = File(context.cacheDir, "http-cache"),
    maxSize = 50L * 1024 * 1024 // 50 MB
)

val client = OkHttpClient.Builder()
    .cache(cache)
    .build()

How Caching Works

1. Client makes a request. OkHttp checks the cache for a matching entry.
2. If the entry exists and is fresh, it returns immediately without network call.
3. If stale, OkHttp sends a conditional request with If-None-Match or If-Modified-Since.
4. Server responds with 304 (use cache) or 200 (new data).

Cache-Control Directives

Offline Caching

For mobile apps that need offline support:

fun buildOfflineRequest(url: String): Request {
    return Request.Builder()
        .url(url)
        .cacheControl(
            CacheControl.Builder()
                .maxStale(7, TimeUnit.DAYS)
                .build()
        )
        .build()
}

The networkBoundResource pattern is standard in Android architecture: return cached data first, fetch fresh data in the background, and fall back to cache on network failure.

HttpLoggingInterceptor

The logging interceptor from OkHttp is essential for debugging. It logs request and response details at different verbosity levels:

val loggingInterceptor = HttpLoggingInterceptor().apply {
    level = when {
        BuildConfig.DEBUG -> HttpLoggingInterceptor.Level.BODY
        else -> HttpLoggingInterceptor.Level.NONE
    }
}

val client = OkHttpClient.Builder()
    .addInterceptor(loggingInterceptor)
    .build()

Warning: Never enable BODY level logging in production. It logs request bodies including passwords and tokens.

Levels Explained

Custom Interceptor for Request IDs

For debugging in production, add a unique request ID to every call:

class RequestIdInterceptor : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val requestId = UUID.randomUUID().toString()
        val request = chain.request().newBuilder()
            .addHeader("X-Request-ID", requestId)
            .build()

        val startNs = System.nanoTime()
        val response = chain.proceed(request)
        val tookMs = (System.nanoTime() - startNs) / 1_000_000
        Log.i("OkHttp", "$requestId ${response.code} in ${tookMs}ms")
        return response
    }
}

This gives you request tracing across your app without logging sensitive payload data. Combine this with crash reporting tools to correlate network failures with user-reported issues.