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.
Retrofit is a REST Client library (Helper Library) used in Android and Java to create an HTTP request and also to process the HTTP response from a REST API. It was created by Square, you can also use retrofit to receive data structures other than JSON, for example SimpleXML and Jackson. Before we continue, let’s briefly define REST Client and REST API in our context.
REST Client in our case is the Retrofit library that is used on the client side (Android) to make HTTP request to REST API, in our case, The Movie DB API and also process the response.
A REST API defines a set of functions which developers can perform requests and receive responses via HTTP protocol such as GET and POST. in our case, The Movie DB (TMDB) API is the REST API.
We can also simply say that a RESTful API is an application program interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data.
To use Retrofit in your Android Application, you’ll need 3 major classes.
- An Interface which defines the HTTP operations (Functions or methods)
According to Square, creators of Retrofit documentation, Retrofit turns your HTTP API into a Java interface. Sample codes for the interface and the method declared in it are as below:
public interface GitHubService {@GET("users/{user}/repos")Call<List<Repo>> listRepos(@Path("user") String user);@GET("group/{id}/users")Call<List<User>> groupList(@Path("id") int groupId);}
Every method inside an interface represents one possible API call. It must have a HTTP annotation (GET, POST, etc.) to specify the request type and the relative URL. The return value wraps the response in a Call object with the type of the expected result.
Query parameters can also be added to a method.
@GET(“group/{id}/users”)Call<List<User>> groupList(@Path(“id”) int groupId, @Query(“sort”) String sort);
You can use replacement blocks and query parameters to adjust the URL. A replacement block is added to the relative URL with {}. With the help of the @Path annotation on the method parameter, the value of that parameter is bound to the specific replacement block.
2. A Retrofit class which generates an implementation of the GitHubService interface. The below sample code would be inside the Retrofit class and this is how it creates an instance of Retrofit and implements the listRepos() method that’s in the GitHubService Interface.
Retrofit retrofit = new Retrofit.Builder().baseUrl(“https://api.github.com/").build();GitHubService service = retrofit.create(GitHubService.class);Call<List<Repo>> repos = service.listRepos(“Gino Osahon”);
3. The last of the 3 needed class is a simple POJO that matches each field in the JSON response object gotten from querying an API. It’s a simple class with getter and setter methods for each fields. We’ll see sample codes later.
Retrofit Converters
Retrofit Converters are like an agreement between and Android client and the Server on the format on which data will be represented. Both parties can agree that for our communication, the format for data transfer will be JSON, as in our case in this tutorial. Remember i said apart from the JSON structure converter, we have others and here are some supported by Retrofit.
Gson:
Gson is for JSON mapping and can be added with the following dependency:
compile ‘com.squareup.retrofit2:converter-gson:2.2.0’
SimpleXML
SimpleXML is for XML mapping. You’ll need the following line for your build.gradle:
compile ‘com.squareup.retrofit2:converter-simplexml:2.2.0’
Jackson
Jackson is an alternative to Gson and claims to be faster in mapping JSON data. The setup offers you a lot more customization and might be worth a look. You can add it with:
compile ‘com.squareup.retrofit2:converter-jackson:2.2.0’
