Tips on updating to Retrofit 2

Retrofit 2.0.0 has been finally released and while the official documentation, articles or blog posts give you all the details about this new version, I’ve seen several questions on StackOverflow about how to update the code just to do the most common tasks like logging, adding request parameters or using JSON objects. So, in this blog post, I will give you a few tips about that.

This article is currently updated with Retrofit v2.0.0.

NEW Group id

The very first change you will notice is the new group idcom.squareup.retrofit2, so that’s the new dependency declaration:

compile 'com.squareup.retrofit2:retrofit:2.0.0'

NEW Package name

Main package name has also changed to:

package retrofit2;

It means you will have to change all the import related to Retrofit. Furthermore, if you perform any processing or manipulation tasks involving package names, remember to update them as well.


Due to the new package name, if you have Proguard enabled on your application, the first thing to do is to update the rules in the configuration file. They are available on the official site:

-dontwarn retrofit2.**
-keep class retrofit2.** { *; }
-keepattributes Signature
-keepattributes Exceptions


OkHttp is now a default dependency and Retrofit 2 builds on top of it. In fact, looking at the Retrofit 2 pom file, there’s the following dependency:


If you don’t need to use a specific version or another client, you don’t have to do anything in this regard.


The next thing you will immediately notice is that the code you have implemented to generate the service interface implementation doesn’t compile anymore.

What follows is the typical and minimal code you would implement on Retrofit:

RestAdapter restAdapter = new RestAdapter.Builder()

GitHubService service = restAdapter.create(GitHubService.class);

In Retrofit 2, this will change to:

Retrofit retrofit = new Retrofit.Builder()

GitHubService service = retrofit.create(GitHubService.class);

As you can see, the Builder pattern has been kept but classes and methods involved have changed.


Being able to log HTTP requests and responses is quite important during development, so if you have enabled this feature on your Retrofit instance, you will find that the method provided to do that is not available anymore.


That’s because now you must rely on the logging system provided by OkHttp, HttpLoggingInterceptor.

The first thing to do is to declare a new dependency, since it’s not part of the main OkHttp artifact:

compile 'com.squareup.okhttp3:logging-interceptor:3.1.2'

Second, create an instance of the interceptor:

HttpLoggingInterceptor httpLoggingInterceptor = new HttpLoggingInterceptor();

Then, add it to the OkHttp client instance:

OkHttpClient okHttpClient = new OkHttpClient.Builder().addInterceptor(httpLoggingInterceptor).build();

And finally set the client while creating the service interface implementation:

Retrofit retrofit = new Retrofit.Builder()

movieDbApi = retrofit.create(MovieDbApi.class);


By default, Retrofit can only deserialize HTTP bodies into OkHttp’s ResponseBody type and it can only accept its RequestBodytype for @Body.

That means a converter must be set while creating the service interface implementation to support other types.

In order to enable Java serialization to convert Java Objects into JSON and back, a GSON converter must be set.

First, a new dependency is required:

compile 'com.squareup.retrofit2:converter-gson:2.0.0'

Then, a converter factory – GsonConverterFactory – must be set:

Retrofit retrofit = new Retrofit.Builder()

movieDbApi = retrofit.create(MovieDbApi.class);

The full list of available converters is available on the official documentation.


Another useful feature of Retrofit is the ability to intercept HTTP calls to monitor, rewrite or retry them for example.

One typical scenario is the requirement to append an API key to all the HTTP requests performed by your application. Prior to Retrofit 2, this could have been achieved declaring a RequestInterceptor:

final RequestInterceptor authorizationInterceptor = new RequestInterceptor() {
        public void intercept(RequestInterceptor.RequestFacade request) {
            request.addQueryParam(MovieDbApi.PARAM_API_KEY, "YOUR_API_KEY");

And the set it in the interface implementation generation:

RestAdapter restAdapter = new RestAdapter.Builder()

movieDbApi = restAdapter.create(MovieDbApi.class);

This is not valid anymore on Retrofit 2 because now you must rely on OkHttp interceptors.

You can directly set one inline while instantiating the OkHttp client:

OkHttpClient okHttpClient = new OkHttpClient.Builder().addInterceptor(new Interceptor() {
    public Response intercept(Chain chain) throws IOException {
        Request request = chain.request();
        HttpUrl url = request.url().newBuilder().addQueryParameter(
MovieDbApi.PARAM_API_KEY, BuildConfig.MOVIE_DB_API_KEY).build();
        request = request.newBuilder().url(url).build();
        return chain.proceed(request);

And then set the client as already shown before:

Retrofit retrofit = new Retrofit.Builder()

movieDbApi = retrofit.create(MovieDbApi.class);

rxjava observable

If you’re using RxJava, you will notice that Retrofit 2 interfaces does not support Observable out of the box anymore: in fact, the Call pattern is used for standard HTTP requests.

Of course, you can use your own type, providing your CallAdapter implementation, but luckily for you there is one already available, RxJavaCallAdapterFactory. In short, it converts a Call to an Observable.

First, add its dependency:


Then, set it using the addCallAdapterFactory method:

Retrofit retrofit = new Retrofit.Builder()

movieDbApi = retrofit.create(MovieDbApi.class);


2 thoughts on “Tips on updating to Retrofit 2”

  1. Hello Daniele,
    Excellent tutorial, thanks for sharing!
    Alias, what is the best way to follow between EventBus3 versus RxAndroid?
    Again, thank you!

    1. Hello Geovani,

      thanks for stopping by! That’s a good question and not an easy one to answer to and I think you can find a lot of “EventBus vs RxJava” articles and blog posts. In my experience, I can say it definitely depends on your application complexity but I would go anyway with RxJava/Android. After you start to have several events, the code can become difficult to read and if not properly done it could increase code coupling. In the Rx world, there are also libraries such as RxLifecycle and RxBinding, so you don’t have to care of lifecycle issues by yourself and manage all the typical widget tasks (clic, scroll, …).
      With RxJava you have also a lot of operators to modify and filter the data stream, which is something missing on EventBus.
      Learning curve is of course quite different: if you go with EventBus in 10 minutes you’ve got all the details and you’re good to go, while RxJava/Android will require a bit of more time.

      Hope it helps.

Leave a Reply

Your email address will not be published. Required fields are marked *