Retrofit library

Retrofit is a type-safe REST client for Java and Android. It requires at minimum Java 8+ or Android API 21+.

Annotations are used to describe the HTTP request:

  • URL parameter replacement and query parameter support
  • object conversion to request body (e.g., JSON, protocol buffers)
  • multipart request body and file upload

Library page on GitHub. Official doc is here.

Add dependency

implementation("com.squareup.retrofit2:retrofit:2.9.0")

1. First define interface of REST service.

public interface GitHubService {
  @GET("users/{user}/repos")
  Call<List<Repo>> listRepos(@Path("user") String user);
  
  @Headers({
    "Accept: application/vnd.github.v3.full+json",
    "User-Agent: Retrofit-Sample-App"
  })
  @GET("users/{username}")
  Call<User> getUser(@Path("username") String username);
  
  @POST("users/new")
  Call<User> createUser(@Body User user);
  
  @FormUrlEncoded
  @POST("user/edit")
  Call<User> updateUser(@Field("first_name") String first, 
      @Field("last_name") String last);
      
  @Multipart
  @PUT("user/photo")
  Call<User> updateUser(@Part("photo") RequestBody photo, 
      @Part("description") RequestBody description);    
  // ...
}

2. Generate an implementation of the interface.

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

GitHubService service = retrofit.create(GitHubService.class);

3. Create Call objects to perform synchronous or asynchronous HTTP requests to the remote webserver.

Call<List<Repo>> repos = service.listRepos("octocat");

// synchronous
Response response = repos.execute();

// asynchronous
repos.enqueue(new Callback<List<Repo>>() {
    @Override
    public void onResponse(Call<List<Repo>> call,
            Response<List<Repo>> response) {
          // request is success, but check response.body() on null
          // ... 
    }
    @Override
    public void onFailure(Call<List<Repo>> call, Throwable t) {
        // error
    }
});

convertes

Retrofit provides different converters to (de)serialize the data. To do this, add the following dependency:

  • Gson: com.squareup.retrofit2:converter-gson
  • Jackson: com.squareup.retrofit2:converter-jackson
  • Moshi: com.squareup.retrofit2:converter-moshi
  • Protobuf: com.squareup.retrofit2:converter-protobuf
  • Wire: com.squareup.retrofit2:converter-wire
  • Simple XML: com.squareup.retrofit2:converter-simplexml
  • JAXB: com.squareup.retrofit2:converter-jaxb
  • Scalars (primitives, boxed, and String): com.squareup.retrofit2:converter-scalars
// Gson allows to convert json response 
// to the java object
Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.github.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .build();

GitHubService service = retrofit.create(GitHubService.class);

adapters

Retrofit ships with a default adapter for executing Call instances. But you can use other popular execution mechanisms like RxJava, Guava, Java 8 (see additional retrofit adapters on github).

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.example.com")
    .addCallAdapterFactory(RxJavaCallAdapterFactory.create())
    .build();