OkHttp Interceptors: Middleware for Your Network Stack

WHY IT EXISTS Modern apps have cross-cutting network concerns like authentication, logging, and caching. Instead of cluttering every API call site with this repetitive logic, OkHttp needed a clean, centralized way to apply these operations to every request. Interceptors provide this single, chainable point of entry.

THE MENTAL MODEL Think of interceptors as a series of checkpoints on a highway. A request starts at one end, and at each checkpoint (interceptor), you can inspect it, modify it, or even turn it around. The request must be passed to the next checkpoint by calling chain.proceed(). The response then travels back through the same checkpoints in reverse order, giving you a chance to inspect or modify it, too.

HOW IT WORKS An interceptor implements a single method, intercept(Chain chain). Inside, you get the request, optionally modify it, and crucially, call chain.proceed(request) to pass it to the next interceptor. There are two types, and their order is critical.

Application Interceptors: Added via addInterceptor(). These run first. They see the raw request you created and are best for high-level logic like adding headers or logging the intended call. They are unaware of network-level details like redirects or retries; they only run once for the initial call.

Network Interceptors: Added via addNetworkInterceptor(). These run last, just before the request goes over the network. They can see the fully-formed request, including any changes made by OkHttp itself (like headers for compression or handling redirects). They are ideal for monitoring the actual bytes going over the wire or measuring latency. They may run multiple times if a request is retried or redirected.

WHEN TO USE IT Use interceptors for app-wide concerns. Three common uses: first, adding an Authorization header to every request; second, logging request and response data for debugging (like OkHttp's own HttpLoggingInterceptor); third, implementing a global error handling strategy, such as refreshing an expired token when you receive a 401 Unauthorized response.

WHEN NOT TO USE IT Avoid interceptors for logic specific to a single API call. If only one endpoint needs a special header, add it when building that specific Request object. Overusing interceptors for endpoint-specific logic makes the system hard to reason about. Also, do not perform long-running, blocking work inside an interceptor, as it will stall the entire network call chain.

ONE CANONICAL EXAMPLE An AuthInterceptor is the classic example. It intercepts every request, creates a new request by adding an Authorization header with a bearer token, and then proceeds with this new, authenticated request. This cleanly separates authentication logic from the code that makes the API calls, which now doesn't need to know or care about how authentication is handled.