skip to content

OkHttp

The JVM and Android HTTP client beneath Retrofit: the interceptor chain, connection pooling, response caching, timeouts and HTTP/2. Interviewers ask how a request moves through it.

on this pageshow

explore

questions

6

Why should an Android app share one OkHttpClient instance, and how does newBuilder() let you customize it without losing that sharing?

level: juniorimportance: must knowfreq 70%

answer

  1. pools and threads live inside
  2. a new client starts cold
  3. derive, don't rebuild
  4. newBuilder keeps pool, dispatcher, cache
  5. reuse needs matching connection settings

basics

~20 s

Each OkHttpClient owns a connection pool and a dispatcher with its own threads, so one shared instance lets calls reuse warm connections. newBuilder() derives a client that keeps the same pool, dispatcher and cache while overriding settings like timeouts.

solid answer

~40 s

An `OkHttpClient` is not just configuration: it holds a `ConnectionPool`, a `Dispatcher` with its executor, and optionally a `Cache`. Since OkHttp 3 every new client gets its own private pool, so a client per request repeats TCP and TLS setup, multiplies idle sockets and threads, and spreads the dispatcher's per-host limit across clients that cannot see each other. The fix is one client at app scope. When one call path needs different settings, call `sharedClient.newBuilder()`: the derived client points at the same pool, dispatcher and cache, gets a copy of the interceptor lists, and lets you override values such as `readTimeout`. Connections are reused across the two only when settings that form the connection's address, such as DNS, protocols or proxy, still match; timeouts are not among them.

go deeper

for a junior

Recall that the client holds a connection pool and a dispatcher, so one shared instance is the rule and newBuilder() is how you vary it.

for a middle

Explain what newBuilder() shares and what it copies: same pool, dispatcher and cache; copied interceptor lists and timeout values.

for a senior

Show you can spot the per-request client in a code review and explain its cost in handshakes, sockets and dispatcher limits that stop working.

for a principal

Frame the shared client as a team default: one app-scope instance, derived variants for the few paths that need them, and a review rule against ad hoc clients.

## What one OkHttpClient owns `OkHttpClient` reads like a bag of settings, but it carries state that is expensive to build and valuable to keep warm: - **A `ConnectionPool`.** Open HTTP/1.1 and HTTP/2 connections are parked here after a response so the next request to the same server skips the TCP and TLS handshakes. By default the pool keeps up to **5 idle connections** and evicts each after **5 minutes** without use. - **A `Dispatcher`.** It runs calls made with `enqueue()` on its executor and enforces two limits: **64** concurrent asynchronous calls in total and **5** per host by default. Its default thread pool creates threads on demand and lets an idle thread exit after 60 seconds. - **An optional `Cache`.** Response caching is off until you pass a `Cache` with a directory and a size. - **Interceptors and an `EventListener.Factory`.** The lists of application and network interceptors, and the factory that creates a metrics listener per call. Everything else on the client, such as timeouts, redirect policy and `retryOnConnectionFailure`, is plain configuration. ## What a client per request costs OkHttp 2 shared one global pool across all clients. Since OkHttp 3 **each new `OkHttpClient` gets its own private pool**, and the 3.0 release notes call out the consequence: many pools prevent connection reuse and each keeps its own idle connections alive. Building a client inside every repository method therefore means: 1. **Cold connections every time.** A brand-new pool is empty, so each call pays DNS, TCP and the TLS handshake again, which on a mobile network is often the slowest part of the request. 2. **More sockets and threads.** Each pool holds its idle connections for up to five minutes and each dispatcher grows its own threads, so resource use scales with the number of clients rather than the number of servers. 3. **Limits that no longer limit.** The per-host cap of 5 lives in one dispatcher; ten clients each enforce their own cap, so a server can see 50 concurrent requests from one app. 4. **Cache hazards.** A `Cache` directory must be owned by exactly one `Cache` instance. Code that creates a client and a new `Cache` on the same directory per call risks corrupting it. ## Customizing with newBuilder() `newBuilder()` returns a builder seeded from an existing client. Building from it produces a new, independent configuration that still shares the expensive parts: | Part of the client | After `sharedClient.newBuilder().build()` | |---|---| | `ConnectionPool` | the same instance | | `Dispatcher` | the same instance, so the same limits and threads | | `Cache` | the same instance | | Interceptor lists | copied into new lists holding the same interceptor objects | | Timeouts, redirects, `retryOnConnectionFailure` | copied as values you may override | So `sharedClient.newBuilder().readTimeout(60, TimeUnit.SECONDS).build()` gives a long-download client whose calls ride the same pool and obey the same dispatcher limits. Adding an interceptor on the derived builder changes only the derived client, because the lists were copied. One nuance decides whether a derived client actually reuses the shared connections. A pooled connection is handed out only when the request's **address** matches: host and port plus the client's `Dns`, proxy settings, `protocols`, connection specs, TLS socket factory, hostname verifier and certificate pinner. Timeouts, interceptors and the cache are not part of the address, so a client that differs only in those reuses everything. A derived client with a different `Dns` or protocol list still shares the pool object, but opens its own connections inside it. ## On Android in practice - **Build it once at app scope**, as a lazily created property of the `Application` or an app-wide singleton from whatever dependency injection the app uses, and build every Retrofit instance on top of it. - **Derive per-purpose clients** for the few call paths that need it: a longer read timeout for large downloads, an extra interceptor for one backend. - **Prefer per-call overrides when a whole client is overkill**: `call.timeout()` sets one call's overall deadline, and an application interceptor can shorten a timeout for a single request. - **Shutting down is not necessary.** Idle threads and connections are released on their own. An app that must release resources aggressively can call `dispatcher.executorService.shutdown()` (future calls are then rejected), `connectionPool.evictAll()` and `cache?.close()`; calls made against a closed cache crash. The interview answer in one line: the client is a resource holder, so you share one and derive variants from it rather than constructing new ones.

  • Do you need to shut down a shared OkHttpClient when the app goes to the background?
    No. OkHttp releases idle resources on its own: the default dispatcher's threads exit after 60 seconds idle and the pool evicts connections after 5 minutes unused. If an app must free them immediately, it can shut down `dispatcher.executorService` (which makes the client reject later calls), call `connectionPool.evictAll()`, and close the cache, accepting that a closed cache makes later calls crash.
  • A client derived with newBuilder() sets its own Dns implementation. Does it reuse the shared client's open connections?
    It shares the same `ConnectionPool` object, but not those connections. A pooled connection is reused only when the request's address matches, and the address includes the client's `Dns`, proxy settings, protocols, connection specs and TLS configuration. A different `Dns` makes a different address, so the derived client opens its own connections inside the shared pool. A derived client that changes only timeouts reuses them.
  • Can two OkHttpClients use one Cache, and can two Cache objects use one directory?
    One `Cache` instance may be shared by several clients, which is exactly what `newBuilder()` does by keeping the same instance. Two `Cache` objects must never point at the same directory: the cache needs exclusive access to it, and two owners can corrupt it or fail at runtime.

  • Create a new OkHttpClient per request so settings never leak between calls.
  • newBuilder() copies the connection pool, so a derived client starts with no warm connections.
  • All OkHttpClient instances share one global connection pool automatically.
  • A shared OkHttpClient must be shut down explicitly or the app leaks threads.
  • Adding an interceptor to a derived builder also adds it to the original client.
open as a page

In OkHttp, how does an application interceptor added with addInterceptor() differ from a network interceptor added with addNetworkInterceptor()?

level: middleimportance: must knowfreq 72%

basics

~20 s

Application interceptors run once per call, see the app's original request and final response, and run for cache hits. Network interceptors run per network exchange, see redirects and OkHttp-added headers, get the Connection, and must call proceed() exactly once.

open as a page

What do OkHttp's connectTimeout, readTimeout, writeTimeout and callTimeout each bound, and which one makes a call to a slow API fail fast?

level: middleimportance: must knowfreq 62%

basics

~20 s

connectTimeout bounds opening a TCP connection; readTimeout and writeTimeout bound each socket read or write; all default to 10 seconds. callTimeout bounds the whole call, retries included, defaults to no limit, and is what makes calls fail fast.

open as a page

How do you turn on OkHttp's response Cache in an Android app, and what do CacheControl.FORCE_CACHE and CacheControl.FORCE_NETWORK change for a request?

level: middleimportance: should knowfreq 45%

basics

~20 s

Pass a Cache(directory, maxSize) to OkHttpClient.Builder().cache(); OkHttp then stores cacheable GET responses following the server's headers. FORCE_CACHE allows only cached data and returns a 504 when nothing usable exists; FORCE_NETWORK skips the cached copy and fetches from the server.

open as a page

An app enqueues 40 concurrent OkHttp calls to one slow API host that speaks HTTP/2; why do most of them wait, and how do you measure and tune it?

level: seniorimportance: should knowfreq 32%

basics

~20 s

OkHttp's Dispatcher runs at most 5 asynchronous calls per host and 64 overall by default, so 35 calls queue even though one HTTP/2 connection could multiplex them. Measure the wait with an EventListener and tune Dispatcher.maxRequestsPerHost.

open as a page

In an OkHttp Interceptor, what are the rules for calling chain.proceed(), and what breaks when an interceptor calls it twice or throws?

level: seniorimportance: should knowfreq 38%

basics

~20 s

chain.proceed() runs the rest of the chain. Network interceptors must call it exactly once; application interceptors may skip it, or repeat it after closing the prior response. A non-IOException cancels the call and, under enqueue() on Android, crashes the app.

open as a page