The latest release of Retrofit 1 (1.9.0) directly depends on OkHttp 2.2.0. For Retrofit 2, the developers introduced multiple breaking changes, because Retrofit in its second major release actually uses OkHttp instead of working with and around it. That means, OkHttp got a lot attention and improvements in regard to functionality and stability. Also, the third major version was just released!
This guide will show you how to make use of OkHttp 3 even though you’re bound to Retrofit 1.
Retrofit Series Overview
- Getting Started and Creating an Android Client
- Basics of API Description
- Creating a Sustainable Android Client
- URL Handling, Resolution and Parsing
- How to Change API Base Url at Runtime
- Multiple Server Environments (Develop, Staging, Production)
- Share OkHttp Client and Converters between Retrofit Instances
- Upgrade Guide from 1.9
- Beyond Android: Retrofit for Java Projects
- How to use OkHttp 3 with Retrofit 1
- Synchronous and Asynchronous Requests
- Send Objects in Request Body
- Add Custom Request Header
- Manage Request Headers in OkHttp Interceptor
- Dynamic Request Headers with @HeaderMap
- Multiple Query Parameters of Same Name
- Optional Query Parameters
- Send Data Form-Urlencoded
- Send Data Form-Urlencoded Using FieldMap
- How to Add Query Parameters to Every Request
- Add Multiple Query Parameter With QueryMap
- How to Use Dynamic Urls for Requests
- Constant, Default and Logic Values for POST and PUT Requests
- Cancel Requests
- Reuse and Analyze Requests
- Optional Path Parameters
- How to Send Plain Text Request Body
- Customize Network Timeouts
- How to Trust Unsafe SSL certificates (Self-signed, Expired)
- Dynamic Endpoint-Dependent Interceptor Actions
- How to Update Objects on the Server (PUT vs. PATCH)
- How to Delete Objects on the Server
- Introduction to (Multiple) Converters
- Adding & Customizing the Gson Converter
- Implementing Custom Converters
- How to Integrate XML Converter
- Access Mapped Objects and Raw Response Payload
- Supporting JSON and XML Responses Concurrently
- Handling of Empty Server Responses with Custom Converter
- Send JSON Requests and Receive XML Responses (or vice versa)
- Unwrapping Envelope Responses with Custom Converter
- Wrapping Requests in Envelope with Custom Converter
- Define a Custom Response Converter
Dependencies
At first you need to add OkHttp 3 to your project. At the time of writing this post, OkHttp 3 was just released, that
means we can directly use the fresh baked cookie :)
Furthermore, you’ll need the wrapper class from Jake Wharton’s retrofit1-okhttp3-client repository on GitHub. Jake already released the client code and you can directly make use of this little helper by importing the Gradle or Maven library. The following code snippets show you the required imports to make Retrofit 1 work with OkHttp 3.
Gradle
compile 'com.squareup.retrofit:retrofit:1.9.0'
compile 'com.squareup.okhttp3:okhttp:3.0.0'
compile 'com.jakewharton.retrofit:retrofit1-okhttp3-client:1.0.2'
Maven
<dependency>
<groupId>com.squareup.retrofit</groupId>
<artifactId>retrofit</artifactId>
<version>1.9.0</version>
</dependency>
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>okhttp</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>com.jakewharton.retrofit</groupId>
<artifactId>retrofit1-okhttp3-client</artifactId>
<version>1.0.2</version>
</dependency>
Use OkHttp 3 Client in RestAdapter
After adding the dependencies to your build.gradle file and finishing the synchronization, you’re ready to plug in the OkHttp 3 client.
The setClient() method on the RestAdapter.Builder expects a Client implementation. Within OkHttp 2, the implementation was called OkClient. For OkHttp 3, Jake Wharton named it Ok3Client and that’s exactly the only thing to change. We just need to pass an Ok3Client object as the parameter for the setClient method.
RestAdapter.Builder builder = new RestAdapter.Builder()
.setClient(new Ok3Client(new OkHttpClient()))
.setEndpoint(API_BASE_URL);
Keep an eye on the OkHttpClient and make sure you’re using the OkHttp 3 version. Because OkHttp introduces the new group id called com.squareup.okhttp3 you’re able to have OkHttp 2 and 3 within your project. The Ok3Client implements the required Client interface, which means there’s nothing more to do than enjoy the new features and improvements of OkHttp 3.
OkHttp 3 Advantages and Features
With the update to OkHttp 3, you’re able to pick up and use the functionality like powerful interceptors. The thing you need to do is using your OkHttpClient for request and response interception instead of Retrofit’s interceptor.
The following code block outlines how to use an OkHttp 3 client with added interceptors and an Authenticator. The advantage in regard to Retrofit’s interceptor is, that you can add multiple of them and not just one.
OkHttpClient.Builder httpBuilder = new OkHttpClient.Builder();
// add interceptors
httpBuilder.addInterceptor(/** Your Interceptor **/)
httpBuilder.addNetworkInterceptor(/** Your Network Interceptor **/)
httpBuilder.authenticator(/** Your Authenticator **/)
// create the OkHttpClient instance from httpBuilder
OkHttpClient client = httpBuilder.build();
RestAdapter.Builder builder = new RestAdapter.Builder()
.setClient(new Ok3Client(client))
.setEndpoint(API_BASE_URL);
We hope that helps to understand how adding OkHttp 3 to your Retrofit 1 project can improve your project’s quality and enables new powerful possibilites (OkHttp 3 interceptors are really powerful!) with the advantages of OkHttp 3.
