Retrofit

Retrofit is a Java library created for the sole purpose of calling REST API easily. As will be shown below, we are basically going to need only some POJO representation of the expected API result, interface to define it, and object repsonsible for using Retrofit.

Example

First we need some pojo representation of our expected JSON result;

public class MyApiPojo {
    private int id;
    private String value;
}

Now we can create simple a interface, that will execute the call to API

public interface MyApiService {
    @GET("/myapi")
    Call<myapipojo> getMyApi();
}

And now the final touch in the matter of retrofit builder

import retrofit2.Retrofit;

public class MyApiServiceProvider {

    private MyApiService myApiService;

    public MyApiServiceProvider() {
        Retrofit retrofit = new Retrofit.Builder()
                .baseUrl("https://api.github.com/")
                .build();
        myApiService = retrofit.create(MyApiService.class);
    }


    public MyApiService getService() {
        return myApiService;
    }
}

With those simple example classes, we’re ready to use REST API on „myapi” endpoint;

MyApiServiceProvider provider = new MyApiServiceProvider();
MyApiService myApiService = provider.getService();
Call<myapipojo> result = myApiService.getMyApi();
Response<myapipojo> response = result.execute();
MyApiPojo pojo = response.body();

As we can see, it is very simple. And yes, Call and Response comes with the Retrofit library.

Some of you may say „What if I want to use query or path param in API?’. Don’t worry, retrofit has a solution for this too:

public interface MyApiService {
    @GET("/myapi/{pathValue}")
    Call<myapipojo> getMyApi(@Path("pathValue") String pathValue, @Query("queryParam") String queryParam);
}

Authorization? Sure thing! Headers definition? They got you boo! You need something else? They probably handled it.

Ok, what just happened?

Let’s take it line by line

@GET("/myapi")
Call<myapipojo> getMyApi();

The very first thing to know is that retrofit uses okhttp3 library. We can even say that retrofit is a wrapper for that library, thus such a small amount of code needed to work. What may seem intriguing in code above, is „Call” generic object, that is just really a wrapper for java „Executor”.

Retrofit retrofit = new Retrofit.Builder()
        .baseUrl("https://api.github.com/")
        .build();
myApiService = retrofit.create(MyApiService.class);

We create a retrofit instance that with the usage of reflection will create a MyApiService proxy (as in Proxy design pattern) instance.

Call<myapipojo> result = myApiService.getMyApi();
Response<myapipojo> response = result.execute();
MyApiPojo pojo = response.body();

Now we can see that the result is just a java executor and the response is just an okhttp3 wrapper. Basically, as mentioned in intro, the sole purpose of retrofit, is just to make REST API calls as simple for the user as possible. And that’s literally it!