REST Easy with Retrofit.
Why making API clients for Android with Retrofit library is the best decision you’ll ever make.
I remember that I was always a very lazy child growing up despite efforts by my parents to make me a hard worker. Given a task , I would often spend hours trying to figure out if there was any other way to do it faster and with less effort. A couple years later, I think this is why I became a programmer and when I first started out Android application development in 2014 I was basically doing things the hard way.
Android Networking Basics.
The first ever android API client I ever made was a weather app connected to Open Weather Map API. I remember having to go through the process of using HttpUrlConnection which is commonly found in the java.net package.
Code which looked something like :
try {
url = new URL(YOUR_REQUEST_URL);
HttpURLConnection urlConnection = (HttpURLConnection) url.openConnection();
urlConnection.setRequestMethod(“GET”);
InputStream inputStream = urlConnection.getInputStream();
//...... Some other stuff then parse the JSON feed into a POJO} catch(Exception ex){ ex.printStackTrace();}
And after doing all that labour, I still had to run it inside an AsyncTask because networking on the main thread forces the app to run into a crash. — Ouch!
Moving On
A couple of months down the line I began exploring for easier options like any lazy lad my age, and I found out about these top dogs namely Volley, AsyncHttpClient and Retrofit.
I found the first two libraries most interesting. AsyncHttpClient would get me up and running using minimal effort. Love at first sight , or so I thought. I came across several issues using AsyncHttpClient for my projects. I was either using it wrong or the library might have had issues. Anyway the effort required to stay in that relationship wasn’t worth it.
Volley was great for me, all of my projects before November 2016 use Volley however it was still a bit of work.
So I moved on to the library built by the gentlemen over at Square and I haven’t looked back since.
Networking using Retrofit.
As seen at their documentation site, Retrofit is a type-safe HTTP client for Android and Java.
Note: This article will focus on Retrofit 2
Retrofit transforms your REST API into a Java interface. You’ll use annotations to describe HTTP requests: url parameter replacement and query parameter support are integrated by default, as well as functionality for multipart request body and file uploads.
It leverages OkHttp to get the job done. OkHttp according to their documentation is an HTTP & HTTP/2 client for android and java. I will not go into the mechanics of that in this article however their documentation is worth taking a look at.
Usage
Retrofit is available as Gradle and Maven dependencies, you’re free to use whichever one suits you. I prefer the Gradle dependency.
Using it in your project is as simple as including the OkHttp and Retrofit libraries in your application level build.gradle file. Its compatible with Java 7 and can be used on devices as early as Android Gingerbread.
dependencies{ //Retrofit
compile 'com.squareup.retrofit2:retrofit:2.1.0'
//Okhttp
compile 'com.squareup.okhttp3:okhttp:3.5.0'}
Never forget to include the internet permission inside the AndroidManifest.xml file within your project.
Declaring an API interface.
We mentioned earlier it turns your REST API into a Java Interface.
An interface will look like the following snippet.
//This is our APIService
public interface NewsService{
//Appends - v1/articles to the base url @GET("v1/articles")
Call<ArticlesResponse> getNewsArticles(@Query("source") String source,@Query("sortBy") String sortBy); }
Breaking down the annotations :
- @GET annotation specifies the request method in this case we are making a GET request to that URL. You can specify other requests like POST, PUT, DELETE.
- @Query annotation specifies a query parameter. We can have as many query parameters as we require and we can include even non-optional ones. It’ll often append a query parameter to create a resolved URL like ‘https://baseurlapi.com/v1/articles?source=newsdayzimbabwe&sortby=asc’ in the case of the snippet.
- Call is an object used to wrap every request, believe me this makes both synchronous and asynchronous requests a breeze.
There are so many additional and quite helpful annotations I will not get into within this article.
You can specify optional parameters by passing in ‘null’ within the interface method implementation. We will get to that in a bit.
Using the API interface.
Executing the request is quite simple. We get an instance of our interface and use the Retrofit.Builder. You should at least define the base url before building. Observe the following snippet.
Retrofit retrofit = new Retrofit.Builder().baseUrl("https://baseurlapi.com/").build();//Then we create our service
NewsService newsService = retrofit.create(NewsService.class);
You’re all set up.
Hold on! Don’t forget the converters!
Requests return responses of different types. The most common in any API is either JSON or XML. The normal or usual thing to do when you receive JSON is parse, deserialize and map it into a POJO class that mimics the response structure.
But that’s also hard work!
The beauty of Retrofit is the fact that you can add converters and get super powers! Well not super powers but you can afford to use less effort with those sweet tools.
I am going to demonstrate the usage of one sibling library for JSON response mapping. All you need to do is define the class of your response object and the rest is automatically done for you.
By adding this one line to your gradle dependency list:
compile 'com.squareup.retrofit2:converter-gson:2.1.0'And adding the GsonConverterFactory class to your builder object, all the JSON serialization and deserialization is all handled for you.
//Add the GSONConverterFactory
Retrofit retrofit = new Retrofit.Builder().baseUrl("https://baseurlapi.com/")
.addConverterFactory(GsonConverterFactory.create())
.build();
Making the request now is as simple as :
Call<ArticlesResponse> call= newsService.getNewsArticles("newsdayzim",null);//Asynchronous request
call.enqueu(new Callback<ArticlesResponse>() {
@Override
public void onResponse(Call<ArticlesResponse> call, Response<ArticlesResponse> response) {
//Get our list of articles
List<Articles> articles = response.body().articles; }
@Override
public void onFailure(Call<ArticlesResponse> call, Throwable t){ //Handle on Failure here
}
});)
Please note: It is recommended to make the request Asynchronous on Android, as synchronous requests may run your app into a crash.
That’s all for now!
Please recommend if you found this helpful. Also leave a comment if you’d like me to do a comparison of Android networking libraries I find useful. I will be sharing Retrofit tips and tricks as we proceed from here on out.
Now if I could just figure out how to automate making my bed.
