2. Tutorials
  3. Retrofit 2 — Share OkHttp Client and Converters between Retrofit Instances

Retrofit 2 — Share OkHttp Client and Converters between Retrofit Instances

Using Retrofit for your Android app's networking can make your life so much easier. However, Retrofit's design requires a single Retrofit instance for each API with a different base URL. Consequently, if your app is talking to two or more APIs (under different URLs), you'll need to deal with at least two Retrofit instances.

If you've multiple Retrofit instances and don't pay attention, you'll lose app performance. In this tutorial, we'll show you how you can share OkHttp as the HTTP network layer between the Retrofit instances, and prevent this loss of performance.

Retrofit Series Overview

  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

Issue of Multiple Retrofit Instances

If your app uses multiple Retrofit instances, your declaration probably looks similar to this:

Retrofit retrofitApiV1 = new Retrofit.Builder()  
        .baseUrl("https://futurestud.io/v1/")
        .addConverterFactory(GsonConverterFactory.create())
        .build();

Retrofit retrofitApiV2 = new Retrofit.Builder()  
        .baseUrl("https://futurestud.io/v2/")
        .addConverterFactory(GsonConverterFactory.create())
        .build();

The example code above uses the same domain, but it could also be two completely different domains, or just different subdomains. In either case, with the example code Retrofit would create a new OkHttp instance for each Retrofit instance. This default behavior leads to at least two separate OkHttp instances, which each keep their own request pooling, disk cache, routing logic, etc.. Because they don't share these, your overall app will unnecessarily lose performance.

Solution 1: Sharing Default OkHttp Instance

In order to make them share a single OkHttp instance, you can simply pass it explicitly on the builder:

OkHttpClient okHttpClient = new OkHttpClient();

Retrofit retrofitApiV1 = new Retrofit.Builder()  
        .baseUrl("https://futurestud.io/v1/")
        .client(okHttpClient)
        .addConverterFactory(GsonConverterFactory.create())
        .build();

Retrofit retrofitApiV2 = new Retrofit.Builder()  
        .baseUrl("https://futurestud.io/v2/")
        .client(okHttpClient)
        .addConverterFactory(GsonConverterFactory.create())
        .build();

The small difference in the new code above causes a shared OkHttp instance and you win back the lost app performance.

If you need two different instances of the OkHttp client, the next section is for you.

Solution 2: Sharing Modified OkHttp Instances

Of course, our example code is simplified. You might already have custom OkHttp clients in your app. Are you stuck when the different APIs you need to talk to require each a custom OkHttp client, e.g., by having different interceptors?

No! You can still share the core (request pooling, disk cache, …) of the OkHttp client between all instances. In order to create custom OkHttp clients, but with a shared core, you can make shallow copies of an OkHttp client by calling .newBuilder():

// core will be shared across both clients
OkHttpClient baseOkHttpClient = new OkHttpClient();

// customize client for first Retrofit instance for API v1
OkHttpClient okHttpClientV1 = baseOkHttpClient  
        .newBuilder()
        .followRedirects(false)
        .build()

Retrofit retrofitApiV1 = new Retrofit.Builder()  
        .baseUrl("https://futurestud.io/v1/")
        .client(okHttpClientV1)
        .addConverterFactory(GsonConverterFactory.create())
        .build();

// customize client for second Retrofit instance for API v2
OkHttpClient okHttpClientV2 = baseOkHttpClient  
        .newBuilder()
        .addInterceptor(...)
        .build()

Retrofit retrofitApiV2 = new Retrofit.Builder()  
        .baseUrl("https://futurestud.io/v2/")
        .client(okHttpClientV2)
        .addConverterFactory(GsonConverterFactory.create())
        .build();

This way, you can customize each OkHttp client to the specific needs, including interceptors. okHttpClientV1 and okHttpClientV2 are customized to the needs of their respective API, but still use the same core. Sharing an OkHttp (core) instance across Retrofit clients can be particularly effective when the servers use HTTP/2, where additional advantages come into play when the APIs live physically on the same server.

Converters

Beware, the negative effect of not sharing resources is also happening (with a less dramatic effect) for converters. For example, this is the code we've shown you above:

OkHttpClient okHttpClient = new OkHttpClient();

Retrofit retrofitApiV1 = new Retrofit.Builder()  
        .baseUrl("https://futurestud.io/v1/")
        .client(okHttpClient)
        .addConverterFactory(GsonConverterFactory.create())
        .build();

Retrofit retrofitApiV2 = new Retrofit.Builder()  
        .baseUrl("https://futurestud.io/v2/")
        .client(okHttpClient)
        .addConverterFactory(GsonConverterFactory.create())
        .build();

Here, we're creating two Gson instances by separately calling GsonConverterFactory.create(). That means those two instances won't share any cache with each other. Instead, you should pass the same Gson (factory) instance to the two Retrofit instances:

GsonConverterFactory gsonFactory = GsonConverterFactory.create();  
OkHttpClient okHttpClient = new OkHttpClient();

Retrofit retrofitApiV1 = new Retrofit.Builder()  
        .baseUrl("https://futurestud.io/v1/")
        .client(okHttpClient)
        .addConverterFactory(gsonFactory)
        .build();

Retrofit retrofitApiV2 = new Retrofit.Builder()  
        .baseUrl("https://futurestud.io/v2/")
        .client(okHttpClient)
        .addConverterFactory(gsonFactory)
        .build();

Don't forget to optimize your app's performance with these small details!

Summary

In this tutorial you've learned that it's important to share the OkHttp instance, or at least its core, and converters between various Retrofit instances. This optimizes your app's performance with a very little implementation detail!

Do you have further questions on this topic or about Retrofit in general? Just let us know on Twitter @futurestud_io or leave a comment below.

Enjoy coding & make it rock!

Additional Resources

Norman Peitek

android & node.js dev

https://twitter.com/peitek

Explore the Library

Find interesting tutorials and solutions for your problems.

Android

Node.js

Server

Miscellaneous