This tutorial only focuses on OkHttp Interceptor. If you want to learn how to send a network request with Retrofit from basics read this
In our last post we have learnt how to send a network request with Retrofit on Android. While Retrofit makes sending HTTP requests quite simple it also allows a unique mechanism to monitor and rewrite these requests. This is implemented with the help of OkHttp Interceptor. Intercept – the word means “to obstruct something from reaching its destinations”, similarly Interceptors obstruct a request, rewrite it and then send it to the destinations(server). For example suppose you need all the HTTP requests sent from your app to have authorization token as header. Instead of dynamically adding the same header to all the endpoints as shown here you can simply add a interceptor which will be invoked every time you send a request.
The official explanation for Interceptors is
Interceptors are to observe, modify and potentially short-circuits requests going out and the corresponding responses coming back in. Typically interceptors add, remove, or transform headers on the request or response.
Interceptors are basically of two types
- Application Interceptors
These are high level interceptors which are used to intercept request and response. They are usually used to rewrite headers/query of both request and response. These are definitly invoked once even if the response is fetched from cache. - Network Interceptors
These are low level interceptors used to monitor requested just as it is transmitted over the network. Are very useful to follow redirects and retries and give access to various low level details of the request. These are not invoked if the response is cached.
The diagram below explains the difference between Network and Application Interceptors
Creating Interceptors
Creating or defining a Interceptor is very simple. You just need to implement the Interceptor interface and override the intercept() method as shown below. The same interface implementation works for both NetworkInterceptor and ApplicationInterceptor
private static class CustomInterceptor implements Interceptor {
@Override
public Response intercept(Chain chain) throws IOException {
/*
chain.request() returns original request that you can work with(modify, rewrite)
*/
Request request = chain.request();
// Here you can rewrite the request
/*
chain.proceed(request) is the call which will initiate the HTTP work. This call invokes the
request and returns the response as per the request.
*/
Response response = chain.proceed(request);
//Here you can rewrite/modify the response
return response;
}
}
A call to chain.proceed(request) is a critical part of each interceptor’s implementation. This simple-looking method is where all the HTTP work happens, this is where the request is initiated and a response is fetched to satisfy the request.
Once you have defined your interface you can register it with the OkHttp client as shown below. Now you should register this client with Retrofit.Builder thereby for all your requests OkHttp client will be used and your interceptor will be invoked
OkHttpClient okHttpClient = new OkHttpClient.Builder()
.addInterceptor(new CustomInterceptor()) // This is used to add ApplicationInterceptor.
.addNetworkInterceptor(new CustomInterceptor()) //This is used to add NetworkInterceptor.
.build();
//Defining the Retrofit using Builder
Retrofit retrofit = new Retrofit.Builder()
.baseUrl(BASE_URL) //This is the onlt mandatory call on Builder object.
.client(okHttpClient) //The Htttp client to be used for requests
.addConverterFactory(GsonConverterFactory.create()) // Convertor library used to convert response into POJO
.build();
Logging Request and Response
As developers it is very important that we log the requests/responses which are sent and received from the app. These logs give us details about the headers, response body, request body and various other details which are crucial for debugging any error. Thanks to Interceptors logging all the HTTP operations on Android is very simple.
Retrofit provides us with a Custom Interceptor – HttpLoggingInterceptor which can be registered with OkHttpClient. With this you will be able to print all the logs for the HTTP operations through this client.
HttpLoggingInterceptor interceptor = new HttpLoggingInterceptor();
interceptor.setLevel(HttpLoggingInterceptor.Level.BODY);
OkHttpClient client = new OkHttpClient.Builder().addInterceptor(interceptor).build();
Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://backend.example.com")
.client(client)
.addConverterFactory(GsonConverterFactory.create())
.build();
Rewriting Requests- Adding/Removing Headers
We have already seen how to define a Custom Interceptor. Now in this section we will define a Custom Interceptor to modify the headers sent with a network request.
private static class RequestInterceptor implements Interceptor {
@Override
public Response intercept(Chain chain) throws IOException {
/*
chain.request() returns original request that you can work with(modify, rewrite)
*/
Request originalRequest = chain.request();
Headers headers = new Headers.Builder()
.add("Authorization", "auth-value")
.add("User-Agent", "you-app-name")
.build();
Request newRequest = originalRequest.newBuilder()
.addHeader("Authorization", "auth-value") //Adds a header with name and value.
.addHeader("User-Agent", "you-app-name")
.cacheControl(CacheControl.FORCE_CACHE) // Sets this request's Cache-Control header, replacing any cache control headers already present.
.headers(headers) //Removes all headers on this builder and adds headers.
.method(originalRequest.method(), null) // Adds request method and request body
.removeHeader("Authorization") // Removes all the headers with this name
.build();
/*
chain.proceed(request) is the call which will initiate the HTTP work. This call invokes the
request and returns the response as per the request.
*/
Response response = chain.proceed(newRequest);
return response;
}
}
Rewriting Response with OKHttp Interceptor
Similarly, OkHttp Interceptor can be used to rewrite/ modify response from the server. With this you can not only rewrite response headers but also can make changes to the response body.
In the example below we read the response code and build a new response body based on the response code.
private static class ResponseInterceptor implements Interceptor {
@Override
public Response intercept(Chain chain) throws IOException {
// We obtain the response using chain.proceed() API. This invokes the request and return the response
Response response = chain.proceed(chain.request());
try {
JSONObject jsonObject = new JSONObject();
if (response.code() == 200) {
jsonObject.put("code", 200);
jsonObject.put("status", "OK");
jsonObject.put("message", new JSONObject(response.body().string()));
} else {
jsonObject.put("code", 404);
jsonObject.put("status", "ERROR");
jsonObject.put("message", new JSONObject(response.body().string()));
}
MediaType contentType = response.body().contentType();
ResponseBody body = ResponseBody.create(contentType, jsonObject.toString());
return response.newBuilder().body(body).build();
} catch (JSONException e) {
e.printStackTrace();
}
return response;
}
}
Android Clarified 