OkHttp interceptors in Android Kotlin - Deep Dive

Overview - OkHttp interceptors

What is it?

OkHttp interceptors are special components that let you watch, modify, or retry network requests and responses in an Android app. They act like checkpoints where you can add headers, log data, or handle errors before the request goes out or after the response comes back. This helps you control how your app talks to the internet in a clean and reusable way.

Why it matters

Without interceptors, you would have to repeat code everywhere you make network calls to add headers or handle errors. This would make your app messy and hard to maintain. Interceptors let you centralize this logic, making your app more reliable and easier to update. They also help with debugging by letting you log network traffic automatically.

Where it fits

Before learning interceptors, you should understand basic OkHttp usage and how HTTP requests and responses work. After mastering interceptors, you can explore advanced networking topics like caching, authentication flows, and custom retry policies.

Mental Model

Core Idea

OkHttp interceptors are like security guards at a gate who check and can change messages going in and out of your app's network calls.

Think of it like...

Imagine sending a letter through a mailroom where a clerk can add stamps, check the address, or even rewrite parts before sending it out or before delivering it back to you. Interceptors are those clerks for your network messages.

┌───────────────┐
│  App Request  │
└──────┬────────┘
       │
┌──────▼────────┐
│ Interceptor 1 │
└──────┬────────┘
       │
┌──────▼────────┐
│ Interceptor 2 │
└──────┬────────┘
       │
┌──────▼────────┐
│  Network Call │
└──────┬────────┘
       │
┌──────▼────────┐
│ Interceptor 2 │
└──────┬────────┘
       │
┌──────▼────────┐
│ Interceptor 1 │
└──────┬────────┘
       │
┌──────▼────────┐
│App Response   │
└───────────────┘

Build-Up - 7 Steps

1

Foundation

What is an OkHttp Interceptor

Concept: Introduces the basic idea of interceptors as components that can observe and modify network requests and responses.

An OkHttp interceptor is a piece of code that sits between your app and the network. It can see every request before it goes out and every response before it reaches your app. You can use it to add headers, log information, or change requests and responses.

Result

You understand that interceptors let you control network calls centrally.

Understanding interceptors as checkpoints helps you see how to add common logic once instead of repeating it everywhere.

2

Foundation

Types of Interceptors: Application vs Network

Concept: Explains the two main types of interceptors and their differences.

OkHttp has two interceptor types: application interceptors and network interceptors. Application interceptors run before the request is sent and after the response is received, even if the response comes from cache. Network interceptors run only when the request actually goes over the network, allowing you to see data as it travels on the wire.

Result

You can decide which interceptor type to use based on whether you want to affect cached responses or only real network traffic.

Knowing the difference prevents bugs like modifying cached data unintentionally or missing network-level details.

3

Intermediate

Creating a Simple Logging Interceptor

🤔Before reading on: do you think interceptors can modify requests, responses, or both? Commit to your answer.

Concept: Shows how to write an interceptor that logs request and response details.

To create a logging interceptor, implement the Interceptor interface and override the intercept(chain) method. Inside, get the request from the chain, log its details, proceed with chain.proceed(request) to get the response, then log response details before returning it.

Result

You get logs of every network call your app makes, helping you debug easily.

Understanding that interceptors can both read and modify requests and responses unlocks powerful customization.

4

Intermediate

Modifying Requests with Interceptors

🤔Before reading on: do you think you can add headers to requests inside interceptors? Commit to yes or no.

Concept: Demonstrates how to add custom headers to every request using an interceptor.

Inside intercept(chain), get the original request, create a new request by adding headers with request.newBuilder().addHeader(), then proceed with the new request. This way, every request your app sends includes the custom header automatically.

Result

Your app sends extra information like API keys or tokens without changing each network call.

Knowing how to modify requests centrally saves time and reduces errors in large apps.

5

Intermediate

Handling Responses and Errors in Interceptors

🤔Before reading on: can interceptors retry failed requests automatically? Commit to yes or no.

Concept: Shows how to inspect responses and retry or handle errors inside interceptors.

After getting the response from chain.proceed(), check its status code. If it's an error like 401 Unauthorized, you can refresh tokens or retry the request. This lets you handle authentication or network errors globally.

Result

Your app can recover from some errors without crashing or user intervention.

Understanding response handling in interceptors enables robust error recovery strategies.

6

Advanced

Chaining Multiple Interceptors and Order Effects

🤔Before reading on: does the order you add interceptors affect how requests and responses are processed? Commit to yes or no.

Concept: Explains how multiple interceptors run in sequence and how their order matters.

Interceptors are called in the order you add them. The first interceptor sees the original request first and the last response last. Changing the order can change behavior, like which headers get added or which logs appear first.

Result

You can design complex request flows by ordering interceptors carefully.

Knowing interceptor order helps prevent subtle bugs and unexpected behaviors in network handling.

7

Expert

Performance and Security Considerations with Interceptors

🤔Before reading on: do interceptors add noticeable delay to network calls? Commit to yes or no.

Concept: Discusses how interceptors impact app performance and security, and best practices to minimize risks.

Interceptors add some processing time to each network call, especially if they do heavy logging or encryption. Overusing interceptors can slow your app. Also, interceptors can expose sensitive data in logs if not careful. Use them wisely, disable verbose logging in production, and avoid blocking operations inside interceptors.

Result

Your app remains fast and secure while benefiting from interceptor features.

Understanding the tradeoffs helps you balance power and performance in real apps.

Under the Hood

OkHttp interceptors work by wrapping the network call in a chain of calls. Each interceptor receives a chain object that lets it access the current request and proceed to the next interceptor or network. This chain pattern allows interceptors to modify requests before passing them on and to inspect or change responses on the way back. The chain ensures that interceptors run in a predictable order and that the final network call happens only once.

Why designed this way?

The chain-of-responsibility pattern was chosen to allow flexible, reusable, and composable network logic. It separates concerns cleanly and avoids duplicating code. Alternatives like callbacks or event listeners would be harder to manage and less predictable. This design also supports both synchronous and asynchronous calls uniformly.

┌───────────────┐
│ Interceptor A │
└──────┬────────┘
       │ calls
┌──────▼────────┐
│ Interceptor B │
└──────┬────────┘
       │ calls
┌──────▼────────┐
│ Network Layer │
└──────┬────────┘
       │ returns
┌──────▼────────┐
│ Interceptor B │
└──────┬────────┘
       │ returns
┌──────▼────────┐
│ Interceptor A │
└──────┬────────┘
       │ returns
┌──────▼────────┐
│   App Layer   │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do application interceptors see cached responses or only network responses? Commit to yes or no.

Common Belief: Application interceptors only see responses that come from the network.

Reality: Application interceptors see all responses, including those served from cache.

Why it matters: If you assume application interceptors only see network responses, you might miss modifying or logging cached data, leading to inconsistent app behavior.

Quick: Can interceptors modify the request after the network call has started? Commit to yes or no.

Common Belief: Interceptors can change requests at any time, even after the network call begins.

Reality: Interceptors can only modify the request before passing it down the chain; once the network call starts, the request is fixed.

Why it matters: Trying to modify requests too late causes bugs or crashes because the network layer expects a finalized request.

Quick: Does adding many interceptors always improve app functionality without downsides? Commit to yes or no.

Common Belief: More interceptors always mean better control and features for network calls.

Reality: Too many interceptors can slow down network calls and complicate debugging.

Why it matters: Overusing interceptors can degrade app performance and make it harder to find bugs.

Quick: Are network interceptors guaranteed to see the exact bytes sent over the wire? Commit to yes or no.

Common Belief: Network interceptors always see the exact raw data sent and received on the network.

Reality: Network interceptors see data after OkHttp's internal transformations like compression or redirects, so not always the raw bytes.

Why it matters: Assuming raw data access can lead to incorrect assumptions about what is logged or modified.

Expert Zone

1

Interceptors can short-circuit the chain by returning a custom response, enabling mock responses or offline mode.

2

Application interceptors are called only once per request, but network interceptors can be called multiple times due to retries or redirects.

3

Interceptors can be used to implement complex authentication flows by chaining token refresh and retry logic seamlessly.

When NOT to use

Avoid using interceptors for heavy data processing or UI updates because they run on network threads and can block calls. For UI-related logic, use callbacks or LiveData. Also, do not use interceptors to handle business logic unrelated to networking; keep them focused on request/response manipulation.

Production Patterns

In production, interceptors are commonly used for adding authentication tokens, logging network traffic with different verbosity levels, retrying failed requests with backoff, and injecting headers like user-agent or locale. They also help implement caching strategies and monitor network performance metrics.

Connections

Middleware in Web Servers

Similar pattern

Both OkHttp interceptors and web server middleware act as layers that process requests and responses in order, allowing modification or inspection at each step.

Aspect-Oriented Programming (AOP)

Builds-on

Interceptors implement cross-cutting concerns like logging or security, similar to how AOP injects behavior around method calls without changing core logic.

Airport Security Checkpoints

Analogy to real-world process

Understanding how passengers are checked multiple times at different gates helps grasp how interceptors inspect and modify network calls at different stages.

Common Pitfalls

#1 Adding heavy blocking operations inside interceptors causing slow network calls.

Wrong approach:

override fun intercept(chain: Interceptor.Chain): Response {
Thread.sleep(5000) // blocks thread for 5 seconds
return chain.proceed(chain.request())
}

Correct approach:

override fun intercept(chain: Interceptor.Chain): Response {
// Do lightweight operations only
return chain.proceed(chain.request())
}

Root cause:

Misunderstanding that interceptors run on network threads and should not block or delay execution.

#2 Modifying the original request without creating a new one, causing errors.

Wrong approach:

val request = chain.request()
request.header("Authorization", "token") // error: Request is immutable
return chain.proceed(request)

Correct approach:

val request = chain.request().newBuilder()
.addHeader("Authorization", "token")
.build()
return chain.proceed(request)

Root cause:

Not knowing that OkHttp requests are immutable and must be rebuilt to change.

#3 Assuming interceptors run only once per request ignoring retries and redirects.

Wrong approach:

Counting on interceptors to run once and caching results inside them without considering multiple calls.

Correct approach:

Design interceptors to be idempotent and handle multiple calls gracefully.

Root cause:

Lack of awareness that network interceptors can be invoked multiple times due to retries or redirects.

Key Takeaways

OkHttp interceptors let you centrally control and modify network requests and responses in Android apps.

There are two types: application interceptors that see all responses including cache, and network interceptors that see only real network traffic.

Interceptors run in a chain, and their order affects how requests and responses are processed.

They enable powerful features like logging, adding headers, error handling, and retry logic without repeating code.

Using interceptors wisely improves app maintainability, debugging, and network reliability but requires care to avoid performance and security issues.

Practice

1. What is the main purpose of an OkHttp interceptor in Android Kotlin?

easy

A. To manage database transactions

B. To observe and modify network requests and responses

C. To create UI components dynamically

D. To handle user input events

Solution

1. Step 1: Understand the role of interceptors

   OkHttp interceptors allow you to watch and change network requests and responses before they are sent or after they are received.

2. Step 2: Compare with other options

   The other options relate to managing database transactions, creating UI components dynamically, and handling user input events, which are unrelated to network interception.

3. Final Answer:

   To observe and modify network requests and responses -> Option B

4. Quick Check:

   Interceptor purpose = Observe and modify network calls [OK]

Hint: Interceptors always deal with network requests/responses [OK]

Common Mistakes:

• Confusing interceptors with UI or database components
• Thinking interceptors handle user input
• Assuming interceptors manage app navigation

2. Which of the following is the correct way to implement an OkHttp interceptor in Kotlin?

easy

A. fun intercept(chain: Chain): Response {
return chain.proceed(chain.request())
}

B. class MyInterceptor : Runnable {
override fun run() {
// code
}
}

C. class MyInterceptor : Interceptor {
override fun intercept(chain: Interceptor.Chain): Response {
return chain.proceed(chain.request())
}
}

D. class MyInterceptor {
fun intercept(chain: Interceptor.Chain) {
// code
}
}

Solution

1. Step 1: Check the interface implementation

   OkHttp interceptors implement the Interceptor interface and override the intercept() method with the correct signature.

2. Step 2: Validate method signature and return type

   The intercept method must take Interceptor.Chain and return a Response object, as shown in class MyInterceptor : Interceptor { override fun intercept(chain: Interceptor.Chain): Response { return chain.proceed(chain.request()) } }.

3. Final Answer:

   Correct interceptor implementation with override and proper method signature -> Option C

4. Quick Check:

   Interceptor class implements Interceptor interface [OK]

Hint: Interceptor must override intercept(chain: Interceptor.Chain): Response [OK]

Common Mistakes:

• Not implementing Interceptor interface
• Wrong method signature or missing return type
• Using unrelated interfaces like Runnable

3. Given this interceptor code snippet, what will be the value of the "User-Agent" header in the outgoing request?

class UserAgentInterceptor : Interceptor {
  override fun intercept(chain: Interceptor.Chain): Response {
    val newRequest = chain.request().newBuilder()
      .header("User-Agent", "MyAppAgent")
      .build()
    return chain.proceed(newRequest)
  }
}

medium

A. The request will have "User-Agent" header set to "MyAppAgent"

B. The request will have no "User-Agent" header

C. The request will have "User-Agent" header set to the default OkHttp value

D. The code will cause a compile error

Solution

1. Step 1: Analyze header modification

   The interceptor creates a new request builder from the original request and sets the "User-Agent" header explicitly to "MyAppAgent".

2. Step 2: Understand header effect

   Setting the header with .header() replaces any existing "User-Agent" header with the new value.

3. Final Answer:

   "User-Agent" header is set to "MyAppAgent" in the outgoing request -> Option A

4. Quick Check:

   Header set by interceptor = "MyAppAgent" [OK]

Hint: .header() replaces existing header values [OK]

Common Mistakes:

• Assuming header is appended instead of replaced
• Thinking default headers remain unchanged
• Confusing compile errors with runtime behavior

4. Identify the error in this interceptor code snippet:

class LoggingInterceptor : Interceptor {
  override fun intercept(chain: Interceptor.Chain): Response {
    val request = chain.request()
    println("Request URL: ${request.url}")
    val response = chain.proceed(request)
    println("Response code: ${response.code}")
  }

medium

A. Missing return statement for the Response object

B. Incorrect method name; should be interceptRequest

C. Cannot use println inside intercept method

D. Request object is not created properly

Solution

1. Step 1: Check method return type

   The intercept method must return a Response object, but this code does not return anything.

2. Step 2: Verify other code parts

   Method name and usage of println are valid; request creation is correct.

3. Final Answer:

   Missing return statement for the Response object -> Option A

4. Quick Check:

   intercept() must return Response [OK]

Hint: Always return the Response from intercept() [OK]

Common Mistakes:

• Forgetting to return the response
• Renaming intercept method incorrectly
• Thinking println is disallowed in intercept

5. You want to create an OkHttp interceptor that retries a request up to 3 times if the response code is 500 (server error). Which approach correctly implements this behavior?

hard

A. Use a separate thread to retry the request after intercept() returns

B. Throw an exception inside intercept() when response code is 500 to trigger retry

C. Modify the request headers to include "Retry: 3" and proceed once

D. Override intercept() to loop up to 3 times calling chain.proceed(request) until response.code != 500 or max retries reached

Solution

1. Step 1: Understand retry logic in intercept()

   Retries must happen inside intercept() by calling chain.proceed(request) multiple times if needed.

2. Step 2: Evaluate options for retry implementation

   Override intercept() to loop up to 3 times calling chain.proceed(request) until response.code != 500 or max retries reached correctly loops and retries up to 3 times checking response code. The other options do not implement retry correctly or rely on unsupported mechanisms.

3. Final Answer:

   Loop inside intercept() to retry request up to 3 times on 500 response -> Option D

4. Quick Check:

   Retry logic = loop in intercept() calling chain.proceed() [OK]

Hint: Retries must be done inside intercept() by repeating chain.proceed() [OK]

Common Mistakes:

• Trying to retry outside intercept() method
• Assuming headers control retry automatically
• Throwing exceptions to trigger retry without handling