Android Retrofit Example

May 30, 2017 by Srinivas

Retrofit http library allows apps to interact with Rest Services. Using Retrofit, one can easily build http get, post, and multipart request components to interact with your application services running on server, meaning building rest clients is easy with Retrofit. Because of its ease of use, this is one of the widely used frameworks in android applications.

Retrofit is not an http client library like apache http client, OkHttp, and HttpUrlConnection. But Retrofit uses http client library and provides type-safe api for apps to interact with Rest Services. By default Retrofit uses OkHttp library as http client.

Retrofit is a type-safe library because it takes care of serialization, deserialization, concurrency and response handling. Retrofit functionality can extended to make it work with libraries like RxJava and Java8 with adapters. Retrofit supports easy plugging capability for converters and adapters.

Retrofit is similar to the other networking library called volley.

Adding Retrofit Libraries

Add below libraries to your project to use retrofit and gson converter. OkHttp is part of retrofit latest version so no need to add it separately to gradle build properties file.

compile 'com.squareup.retrofit2:retrofit:2.3.0'
compile 'com.google.code.gson:gson:2.8.0'
compile 'com.squareup.retrofit2:converter-gson'

Creating Rest Service Client Using Retrofit

Below are the steps to create retrofit service client and use it to get response from server.

Define api interface using appropriate annotations. You can get more details on retrofit annotations in below sections.

 public interface CouponApi {
    @GET("coupons/")
    Call<CouponsWrapper> getCoupons(@Query("status") String status);
}

Build Retrofit object using Retrofit.Builder. You can set base url and converter etc.

 Retrofit retrofit = new Retrofit.Builder()
        .baseUrl(BASE_URL)
        .addConverterFactory(GsonConverterFactory.create())
        .build();

Create service client, which is an implementation of api interface you defined, using the Retrofit object, passing your api interface to create() method on Retrofit object.
```
 CouponApi couponService = retrofit.create(CouponApi.class); 
```

Now, you can use the service client to create Call object.

 Call<CouponsWrapper> call = couponService.getCoupons("latest");

To send request to server and get response, you can either call execute method to make synchronous request or call enqueue method to make asynchronous request on Call object.
```
    Response<CouponsWrapper> rp  =  call.execute();
                return rp.body(); 
```

Retrofit Converters

To make retrofit convert the responses it receives from server, from different formats to java objects and from java objects to other formats which services take as input, you need to add converters to retrofit. For example, to convert json response to your java model object or java model object to Json, you need to add gson converter to retrofit.

Retrofit provides converters for various serialization libraries like gson, jacson, moshi and simple xml.

Converter can be added by calling addConverterFactory method on Retrofit.Builder object.

Retrofit retrofit = new Retrofit.Builder()  
        .baseUrl("http://...")
        .addConverterFactory(GsonConverterFactory.create())
        .build();

Retrofit Call Adapters

You can plug adapters to retrofit to make retrofit workable with other libraries like RxJava, Guva and Java 8. Retrofit services can return types from other libraries with adapters. For example, to make retrofit service return object types from RxJava, you need to add RxJava adapter as shown below.

You can add adapters to retrofit by calling addCallAdapterFactory method on Retrofit.Builder class.

 Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("http//...")
    .addCallAdapterFactory(RxJava2CallAdapterFactory.create())
    .build();

 Observable<Coupons> latestCoupons = couponService.getCoupons("latest");

Android Retrofit Get

To send a get request using retrofit, you need to define the method in your api interface with GET annotation as shown below.

    @GET("coupons/")
    Call<CouponsWrapper> getCoupons();

Android Retrofit Get With QueryString

To pass query string with http get request using retrofit, annotate input parameter with QUERY. You can define parameter name by passing it to QUERY annotation.

    @GET("coupons/")
    Call<CouponsWrapper> getCoupons(@Query("status") String status);

Android Retrofit Dynamic Url

You can create dynamic URLs with retrofit using {} in the path and PATH annotation.

    @GET("coupon/{store}")
    Call<CouponsWrapper> getCoupons(@Path("store") String storename);

Android Retrofit Post Form

To send post request with parameters and their values like submitting an html forms, you need to annotate the method with @FormUrlEncoded and @POST and annotate each parameter you want to send in the post request with @Field.

    @FormUrlEncoded    
    @POST("coupons/")
    Call<CouponsWrapper> getCoupons(@Field("store") String storeName, @Field("category") String category);

Android Retrofit Post Json

To send Json request to server, annotate method with POST and annotate input java object which contains json data with Body annotation as shown below. In order for this to work, you need to add gson converter, retrofit uses this to convert java object annotated as body to Json string which will be sent to server as request body.

    @POST("add/coupons")
    Call<String> loadCoupons(@Body Coupons);

Android Retrofit Multipart

To define api which sends multipart data to server, for example image and title of image, you need to annotate the api method with @Multipart and @PUT, and annotate parts with @Part annotation.

    @Multipart
    @PUR("uploadCoupons/")
    Call<String> uploadCoupons(@Part("xml") RequestBody couponXml, @Part("date") RequestBody date);

Android Retrofit Asynchronous Request

As mentioned before, http request can be sent to server synchronously (on the main thread) by calling execute method or asynchronously (on worker thread) by calling enqueue method on the Call object passing Callback object which handles response and error.

          call.enqueue(new Callback<CouponsWrapper>() {
                @Override
                public void onResponse(Call<CouponsWrapper> call, Response<CouponsWrapper> response) {
                    response.body().getCouponList();
		    Log.d(TAG, "got response from service using retrofit, performing further processing");
                }

                @Override
                public void onFailure(Call<CouponsWrapper> call, Throwable t) {
 		    Log.e(TAG, "error in getting response from service using retrofit");
                }
            });

Android Retrofit Adding Header

Headers can be added to request by annotating your api method with Headers annotation.

    @Headers({"Cache-Control: max-age=200000", "Authorization: askjfaks"})
    @GET("coupons/")
    Call<CouponsWrapper> getCoupons(@Query("status") String status);