2. Tutorials
  3. Retrofit — Add Custom Request Header

Retrofit — Add Custom Request Header

You’ve already learned how to integrate authentication with Retrofit, how to pass multiple query parameter values for the same identifier. Additionally, if you read the previously published articles within this series, you know how to create your own custom response converter and register it into the Retrofit instance.

This tutorial shows you how to add custom headers to your requests by using the @Header annotation within your interface definition or by intercepting the request and add defined header fields with their values.

Retrofit Series Overview

  1. Getting Started and Creating an Android Client
  2. Basics of API Description
  3. Creating a Sustainable Android Client
  4. URL Handling, Resolution and Parsing
  5. How to Change API Base Url at Runtime
  6. Multiple Server Environments (Develop, Staging, Production)
  7. Share OkHttp Client and Converters between Retrofit Instances
  8. Upgrade Guide from 1.9
  9. Beyond Android: Retrofit for Java Projects
  10. How to use OkHttp 3 with Retrofit 1
  1. Synchronous and Asynchronous Requests
  2. Send Objects in Request Body
  3. Add Custom Request Header
  4. Manage Request Headers in OkHttp Interceptor
  5. Dynamic Request Headers with @HeaderMap
  6. Multiple Query Parameters of Same Name
  7. Optional Query Parameters
  8. Send Data Form-Urlencoded
  9. Send Data Form-Urlencoded Using FieldMap
  10. How to Add Query Parameters to Every Request
  11. Add Multiple Query Parameter With QueryMap
  12. How to Use Dynamic Urls for Requests
  13. Constant, Default and Logic Values for POST and PUT Requests
  14. Cancel Requests
  15. Reuse and Analyze Requests
  16. Optional Path Parameters
  17. How to Send Plain Text Request Body
  18. Customize Network Timeouts
  19. How to Trust Unsafe SSL certificates (Self-signed, Expired)
  20. Dynamic Endpoint-Dependent Interceptor Actions
  21. How to Update Objects on the Server (PUT vs. PATCH)
  22. How to Delete Objects on the Server
  1. Ignore Response Payload with Call<Void>
  2. Receive Plain-String Responses
  3. Crawl HTML Responses with jspoon (Wikipedia Example)
  4. Loading Data into RecyclerView and CardView
  1. Introduction to (Multiple) Converters
  2. Adding & Customizing the Gson Converter
  3. Implementing Custom Converters
  4. How to Integrate XML Converter
  5. Access Mapped Objects and Raw Response Payload
  6. Supporting JSON and XML Responses Concurrently
  7. Handling of Empty Server Responses with Custom Converter
  8. Send JSON Requests and Receive XML Responses (or vice versa)
  9. Unwrapping Envelope Responses with Custom Converter
  10. Wrapping Requests in Envelope with Custom Converter
  11. Define a Custom Response Converter
  1. Simple Error Handling
  2. Error Handling for Synchronous Requests
  3. Catch Server Errors Globally with Response Interceptor
  4. How to Detect Network and Conversion Errors in onFailure
  1. Log Requests and Responses
  2. Enable Logging for Development Builds Only
  3. Log Network Traffic with Stetho and Chrome Developer Tools
  4. Using the Log Level to Debug Requests
  5. Analyze Network Traffic with Android Studio Profiler
  6. Debug and Compare Requests with RequestBin
  1. Introduction to Call Adapters
  2. Custom Call Adapter to Separate OnResponse Callback
  3. How to Integrate RxJava 1.x Call Adapter
  4. How to Integrate RxJava 2.x Call Adapter
  5. How to Integrate Guava Call Adapter
  6. Custom Call Adapter to Separate Network and Gson Errors
  1. Pagination Using Query Parameter
  2. Pagination Using Link Header and Dynamic Urls (Like GitHub)
  3. Pagination Using Range Header Fields (Like Heroku)
  1. How to Upload Files to Server
  2. How to Upload Multiple Files to Server
  3. How to Upload a Dynamic Amount of Files to Server
  4. Upload Files with Progress
  5. Passing Multiple Parts Along a File with @PartMap
  6. How to Download Files from Server
  7. Download Files with Progress Updates
  8. How to Upload Files to Server
  1. Basic Authentication on Android
  2. Token Authentication on Android
  3. OAuth on Android
  4. Hawk Authentication on Android
  5. How to Refresh an Access Token
  1. Activate Response Caching (Etag, Last-Modified)
  2. Check Response Origin (Network, Cache, or Both)
  3. Force Server Cache Support with Response Interceptor
  4. Support App Offline Mode by Accessing Response Caches
  5. Analyze Cache Files
  1. Basics of Mocking Server Responses
  2. Customizing Network Behavior of Mocked Server Responses
  3. Mock APIs with JsonServer
  1. Callbacks
  2. Annotations
  3. Fluent Interface with Builders

Define Custom Request Headers

Retrofit provides two options to define HTTP request header fields: static and dynamic. Static headers can’t be changed for different requests. The header’s key and value are fixed and initiated with the app startup.

In contrast, dynamic headers must be set for each request.

Static Request Header

The first option to add a static header is to define the header and respective value for your API method as an annotation. The header gets automatically added by Retrofit for every request using this method. The annotation can be either key-value-pair as one string or as a list of strings. Let's face two specific examples which illustrate the definition options:

Retrofit 2

public interface UserService {  
    @Headers("Cache-Control: max-age=640000")
    @GET("/tasks")
    Call<List<Task>> getTasks();
}

Retrofit 1.9

public interface UserService {  
    @Headers("Cache-Control: max-age=640000")
    @GET("/tasks")
    List<Task> getTasks();
}

The example above shows the key-value-definition for the static header. Further, you can pass multiple key-value-strings as a list encapsulated in curly brackets {} to the @Headers annotation.

Retrofit 2

public interface UserService {  
    @Headers({
        "Accept: application/vnd.yourapi.v1.full+json",
        "User-Agent: Your-App-Name"
    })
    @GET("/tasks/{task_id}")
    Call<Task> getTask(@Path("task_id") long taskId);
}

Retrofit 1.9

public interface UserService {  
    @Headers({
        "Accept: application/vnd.yourapi.v1.full+json",
        "User-Agent: Your-App-Name"
    })
    @GET("/tasks/{task_id}")
    Task getTask(@Path("task_id") long taskId);
}

Additionally, you can define static headers via the intercept method of Retrofits RequestInterceptor (customized implementation of the Interceptor interface in Retrofit 2). We already used the RequestInterceptor within the previous tutorials (Basic and Token Auth, OAuth) and of course you can enhance it by setting header fields.

Retrofit 2

In Retrofit 2, you need to intercept the request on the network layer provided by OkHttp.

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

        Request request = original.newBuilder()
            .header("User-Agent", "Your-App-Name")
            .header("Accept", "application/vnd.yourapi.v1.full+json")
            .method(original.method(), original.body())
            .build();

        return chain.proceed(request);
    }
}

OkHttpClient client = httpClient.build();  
Retrofit retrofit = new Retrofit.Builder()  
    .baseUrl(API_BASE_URL)
    .addConverterFactory(GsonConverterFactory.create())
    .client(client)
    .build();

Retrofit 1.9

RequestInterceptor requestInterceptor = new RequestInterceptor() {  
    @Override
    public void intercept(RequestFacade request) {
        request.addHeader("User-Agent", "Your-App-Name");
        request.addHeader("Accept", "application/vnd.yourapi.v1.full+json");
    }
};

RestAdapter restAdapter = new RestAdapter.Builder()  
    .setEndpoint("https://api.github.com")
    .setRequestInterceptor(requestInterceptor)
    .build();

As you can see, the examples above set the User-Agent and Accept header fields with respective values. These values are passed with every request which is executed using the RestAdapter (Retrofit in Retrofit 2) and the integrated RequestInterceptor (Interceptor in Retrofit 2).

Dynamic Header

A more customizable approach are dynamic headers. A dynamic header is passed like a parameter to the method. The provided parameter value gets mapped by Retrofit before executing the request. Let's look at the code example:

Retrofit 2

public interface UserService {  
    @GET("/tasks")
    Call<List<Task>> getTasks(@Header("Content-Range") String contentRange);
}

Retrofit 1.9

public interface UserService {  
    @GET("/tasks")
    List<Task> getTasks(@Header("Content-Range") String contentRange);
}

Define dynamic headers where you might pass different values for each request. The example illustrates the dynamic header with Content-Range definition.

No Header Override in Retrofit 1

Remember: Retrofit doesn't override header definitions with the same name. Every defined header is added to the request.

That's it. Retrofit simplifies header manipulation and allows to simply change them for separated requests when necessary.

In case things went south, give us a shot on twitter @futurestud_io.

Override Existing Headers in Retrofit 2

As opposed to Retrofit v1, you can override the values of existing header fields. You can override the values within the Interceptor implementation passed to the used OkHttp client. The Request.Builder offers two methods to add headers:

  1. .header(key, value): overrides the respective header key with value if there is already an existing header identified by key
  2. .addHeader(key, value): adds the respective header key and value even if there is an existing header field with the same key

Summary

In this tutorial you've learned how you can add custom request header to your Retrofit requests. You can add headers dynamically or in a static way.

If you've any questions, let us know on Twitter @futurestud_io or in the comment section below.

Enjoy coding & make it rock!

Additional Resources

Marcus Pöhls

Marcus is a fullstack JS developer. He’s passionate about the hapi framework for Node.js and loves to build web apps and APIs. Creator of Futureflix and the “learn hapi” learning path.

Explore the Library

Find interesting tutorials and solutions for your problems.

Android

Node.js

Server

Miscellaneous