Introduction to Retrofit

1. Overview

Retrofit is a type-safe HTTP client for Android and Java – developed by Square (Dagger, Okhttp).

In this article, we’re going to explain how to use Retrofit, with a focus on its most interesting features. More notably we’ll discuss the synchronous and asynchronous API, how to use it with authentication, logging, and some good modeling practices.

2. Setting up the Example

We’ll start by adding the Retrofit library and the Gson converter:

<dependency>
    <groupId>com.squareup.retrofit2</groupId>
    <artifactId>retrofit</artifactId>
    <version>2.3.0</version>
</dependency>  
<dependency>  
    <groupId>com.squareup.retrofit2</groupId>
    <artifactId>converter-gson</artifactId>
    <version>2.3.0</version>
</dependency>

For the latest versions, have a look at Retrofit and converter-gson on Maven Central repository.

3. API Modeling

Retrofit models REST endpoints as Java interfaces, making them very simple to understand and consume.

We’ll model the user API from GitHub; this has a GET endpoint that returns this in JSON format:

{
  login: "mojombo",
  id: 1,
  url: "https://api.github.com/users/mojombo",
  ...
}

Retrofit works by modeling over a base URL and by making interfaces return the entities from the REST endpoint.

For simplicity purposes we’re going to take a small part of the JSON by modeling our User class that is going to take the values when we have received them:

public class User {
    private String login;
    private long id;
    private String url;
    // ...

    // standard getters an setters

}

We can see that we’re only taking a subset of properties for this example. Retrofit won’t complain about missing properties – since it only maps what we need, it won’t even complain if we were to add properties that are not in the JSON.

Now we can move to the interface modeling, and explain some of the Retrofit annotations:

public interface UserService {

    @GET("/users")
    public Call<List<User>> getUsers(
      @Query("per_page") int per_page, 
      @Query("page") int page);

    @GET("/users/{username}")
    public Call<User> getUser(@Path("username") String username);
}

The metadata provided with annotations is enough for the tool to generate working implementations.

The @GET annotation tells the client which HTTP method to use and on which resource, so for example, by providing a base URL of “https://api.github.com” it will send the request to “https://api.github.com/users”.

The leading “/” on our relative URL tells Retrofit that it is an absolute path on the host.

Another thing to note is that we use completely optional @Query parameters, which can be passed as null if we don’t need them, the tool will take care of ignoring these parameters if they do not have values.

And last but not least, @Path lets we specify a path parameter that will be placed instead of the markup we used in the path.

4. Synchronous/Asynchronous API

To construct an HTTP request call, we need to build our Retrofit object first:

OkHttpClient.Builder httpClient = new OkHttpClient.Builder();
Retrofit retrofit = new Retrofit.Builder()
  .baseUrl("https://api.github.com/")
  .addConverterFactory(GsonConverterFactory.create())
  .client(httpClient.build())
  .build();

Retrofit provides a convenient builder for constructing our required object. It needs the base URL which is going to be used for every service call and a converter factory – which takes care of the parsing of data we’re sending and also the responses we get.

In this example, we’re going to use the GsonConverterFactory, which is going to map our JSON data to the User class we defined earlier.

It’s important to note that different factories serve different purposes, so keep in mind that we can also use factories for XML, proto-buffers or even create one for a custom protocol. For a list of already implemented factories, we can have a look here.

The last dependency is OKHttpClient – which is an HTTP & HTTP/2 client for Android and Java applications. This is going to take care of connecting to the server and the sending and retrieval of information. We could also add headers and interceptors for every call, which we’re going to see in our authentication section.

Now that we have our Retrofit object, we can construct our service call, let’s take a look at how to do this the synchronous way:

UserService service = retrofit.create(UserService.class);
Call<User> callSync = service.getUser("eugenp");

try {
    Response<User> response = callSync.execute();
    User user = response.body();
} catch (Exception ex) { ... }

Here, we can see how Retrofit takes care of the construction of our service interface by injecting the code necessary to make the request, based on our previous annotations.

After that, we get a Call<User> object which is the one used for executing the request to the GitHub API. The most important method here is execute, which is used to execute a call synchronously and will block the current thread while transferring the data.

After the call is executed successfully, we can retrieve the body of the response – already on a user object – thanks to our GsonConverterFactory.

Making a synchronous call is very easy, but usually, we use a non-blocking asynchronous request:

UserService service = retrofit.create(UserService.class);
Call<User> callAsync = service.getUser("eugenp");

callAsync.enqueue(new Callback<User>() {
    @Override
    public void onResponse(Call<User> call, Response<User> response) {
        User user = response.body();
    }

    @Override
    public void onFailure(Call<User> call, Throwable throwable) {
        System.out.println(throwable);
    }
});

Now instead of the execute method, we use the enqueue method – which takes a Callback<User>interface as a parameter to handle the success or failure of the request. Note that this will execute in a separate thread.

After the call finished successfully, we can retrieve the body the same way we did previously.

5. Making a Reusable ServiceGenerator Class

Now that we saw how to construct our Retrofit object and how to consume an API, we can see that we don’t want to keep writing the builder over and over again.

What we want is a reusable class that allows us to create this object once and reuse it for the lifetime of our application:

public class GitHubServiceGenerator {

    private static final String BASE_URL = "https://api.github.com/";

    private static Retrofit.Builder builder
      = new Retrofit.Builder()
        .baseUrl(BASE_URL)
        .addConverterFactory(GsonConverterFactory.create());

    private static Retrofit retrofit = builder.build();

    private static OkHttpClient.Builder httpClient
      = new OkHttpClient.Builder();

    public static <S> S createService(Class<S> serviceClass) {
        return retrofit.create(serviceClass);
    }
}

All the logic of creating the Retrofit object is now moved to this GitHubServiceGenerator class, this makes it a sustainable client class which stops the code from repeating.

Here’s a simple example of how to use it :

UserService service 
  = GitHubServiceGenerator.createService(UserService.class);

Now if we, for example, were to create a RepositoryService, we could reuse this class and simplify the creation.

In the next section, we’re going to extend it and add authentication capabilities.

6. Authentication

Most APIs have some authentication to secure access to it.

Taking into account our previous generator class, we’re going to add a create service method, that takes a JWT token with the Authorization header :

public static <S> S createService(Class<S> serviceClass, final String token ) {
   if ( token != null ) {
       httpClient.interceptors().clear();
       httpClient.addInterceptor( chain -> {
           Request original = chain.request();
           Request request = original.newBuilder()
             .header("Authorization", token)
             .build();
           return chain.proceed(request);
       });
       builder.client(httpClient.build());
       retrofit = builder.build();
   }
   return retrofit.create(serviceClass);
}

To add a header to our request, we need to use the interceptor capabilities of OkHttp; we do this by using our previously define builder and by reconstructing the Retrofit object.

Note that this a simple auth example, but with the use of interceptors we can use any authentication such as OAuth, user/password, etc.

7. Logging

In this section, we’re going to further extend our GitHubServiceGenerator for logging capabilities, which are very important for debugging purposes in every project.

We’re going to use our previous knowledge of interceptors, but we need an additional dependency, which is the HttpLoggingInterceptor from OkHttp, let us add it to our pom.xml:

<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>logging-interceptor</artifactId>
    <version>5.0.0-alpha.12</version>
</dependency>

Now let us extend our GitHubServiceGenerator class :

public class GitHubServiceGenerator {

    private static final String BASE_URL = "https://api.github.com/";

    private static Retrofit.Builder builder
      = new Retrofit.Builder()
        .baseUrl(BASE_URL)
        .addConverterFactory(GsonConverterFactory.create());

    private static Retrofit retrofit = builder.build();

    private static OkHttpClient.Builder httpClient
      = new OkHttpClient.Builder();

    private static HttpLoggingInterceptor logging
      = new HttpLoggingInterceptor()
        .setLevel(HttpLoggingInterceptor.Level.BASIC);

    public static <S> S createService(Class<S> serviceClass) {
        if (!httpClient.interceptors().contains(logging)) {
            httpClient.addInterceptor(logging);
            builder.client(httpClient.build());
            retrofit = builder.build();
        }
        return retrofit.create(serviceClass);
    }

    public static <S> S createService(Class<S> serviceClass, final String token) {
        if (token != null) {
            httpClient.interceptors().clear();
            httpClient.addInterceptor( chain -> {
                Request original = chain.request();
                Request.Builder builder1 = original.newBuilder()
                  .header("Authorization", token);
                Request request = builder1.build();
                return chain.proceed(request);
            });
            builder.client(httpClient.build());
            retrofit = builder.build();
        }
        return retrofit.create(serviceClass);
    }
}

This is the final form of our class, we can see how we added the HttpLoggingInterceptor, and we set it for basic logging, which is going to log the time it took to make the request, the endpoint, status for every request, etc.

It’s important to take a look at how we check if the interceptor exists, so we don’t accidentally add it twice.

8. Conclusion

In this extensive guide, we took a look at the excellent Retrofit library by focusing on its Sync/Async API, some best practices of modeling, authentication, and logging.

The library can be used in very complex and useful ways; for an advanced use case with RxJava, please take a look at this tutorial.