Retrofit 2 — Manage Request Headers in OkHttp Interceptor

You’ve already learned how to add custom request header using Retrofit. This post specifically touches the details on adding request headers using Retrofit 2 and the OkHttp interceptor. Interceptors are a good way to statically change requests executed with the specific service client which has the interceptor assigned.

Retrofit Series Overview

  1. Introduction to Call Adapters (Coming soon)
  1. Callbacks (Coming soon)
  2. Annotations (Coming soon)
  3. Fluent Interface with Builders (Coming soon)

Add Request Headers

Adding HTTP request headers is a good practice to add information for API requests. A common example is authorization using the Authorization header field. If you need the header field including its value on almost every request, you can use an interceptor to add this piece of information. This way, you don’t need to add the @Header annotation to every endpoint declaration.

OkHttp interceptors offer two ways to add header fields and values. You can either override existing headers with the same key or just add them without checking if there is another header key-value-pair already existing. We’ll walk you through both of them in the following paragraphs.

How to Override Headers

Intercepting HTTP requests with the help of OkHttp interceptors allows you to manipulate the actual request and apply your customization. The request builder has a .header(key, val) method which will add your defined header to the request. If there is already an existing header with the same key identifier, this method will override the previously defined value.

OkHttpClient.Builder httpClient = new OkHttpClient.Builder();  
httpClient.addInterceptor(new Interceptor() {  
    @Override
    public Response intercept(Interceptor.Chain chain) throws IOException {
        Request original = chain.request();

        // Request customization: add request headers
        Request.Builder requestBuilder = original.newBuilder()
                .header("Authorization", "auth-value"); // <-- this is the important line

        Request request = requestBuilder.build();
        return chain.proceed(request);
    }
});

OkHttpClient client = httpClient.build();  

Retrofit, and especially OkHttp, allow you to add multiple headers with the same key. The .header method will replace all existing headers with the defined key identifier. Within the code snippet above, every Authorization header (if multiple have been defined already) will be updated and their previous value will be replaced with auth-value.

How to Not Override Headers

There are situations where multiple headers with the same name are used. Actually, we’re only aware of one specific example from practise: the Cache-Control header. The HTTP RFC2616 specifies that multiple header values with the same name are allowed if they can be stated as a comma-separated list.

That means,

Cache-Control: no-cache  
Cache-Control: no-store  

is the same as

Cache-Control: no-cache, no-store  

Using Retrofit 2 and an OkHttp interceptor, you can add multiple request headers with the same key. The method you need to use is .addHeader.

The following example will add the Cache-Control headers from the example above:

OkHttpClient.Builder httpClient = new OkHttpClient.Builder();  
httpClient.addInterceptor(new Interceptor() {  
    @Override
    public Response intercept(Interceptor.Chain chain) throws IOException {
        Request original = chain.request();

        // Request customization: add request headers
        Request.Builder requestBuilder = original.newBuilder()
                    .addHeader("Cache-Control", "no-cache")
                    .addHeader("Cache-Control", "no-store");

        Request request = requestBuilder.build();
        return chain.proceed(request);
    }
});

OkHttpClient client = httpClient.build();  

Take Away

Notice the small but mighty difference:

  • .header(key, val): will override preexisting headers identified by key
  • .addHeader(key, val): will add the header and don’t override preexisting ones

Make sure you’re using the appropriate method to achieve your desired request results.

Outlook

This post walked you through the different methods on how to add request headers using OkHttp’s request interceptors. Customizing the request and adding request header enable a simple and effective way to pass data with every request. This method will result in much cleaner code than adding header fields with the @Header annotation for every request.


Explore the Library

Find interesting tutorials and solutions for your problems.

Miscellaneous