Tạo ứng dụng Java RESTful Client với thư viện Retrofit

Trong các bài viết trước chúng ta sử dụng thư viện Jersey client, OkHttp để gọi các RESTful API. Trong bài này, tôi sẽ giới thiệu với các bạn thư viện khác là Retrofit.

1. Giới thiệu Retrofit

Retrofit là một type-safe HTTP client cho Java và Android được phát triển bởi Square. Retrofit giúp dễ dàng kết nối đến một dịch vụ REST trên web bằng cách chuyển đổi API thành Java Interface.

Tương tự với các thư viện khác, Retrofit giúp bạn dễ dàng xử lý dữ liệu JSON hoặc XML sau đó phân tích cú pháp thành Plain Old Java Objects (POJOs). Tất cả các yêu cầu GET, POST, PUT, và DELETE đều có thể được thực thi.

Retrofit được xây dựng dựa trên một số thư viện mạnh mẽ và công cụ khác. Đằng sau nó, Retrofit làm cho việc sử dụng OkHttp để xử lý các request/ response trên mạng. Ngoài ra, từ Retrofit2 không tích hợp bất kỳ một bộ chuyển đổi JSON nào để phân tích từ JSON thành các đối tượng Java. Thay vào đó nó đi kèm với các thư viện chuyển đổi JSON sau đây:

• Gson: com.squareup.retrofit2:converter-gson
• Jackson: com.squareup.retrofit2:converter-jackson
• Xem thêm các thư viện khác: https://mvnrepository.com/artifact/com.squareup.retrofit2

2. Sử dụng retrofit

Để sử dụng Retrofit chúng ta thực hiện các bước sau:

• Một class object tương ứng với JSON/ XML data.
• Một interface dùng để định nghĩa các các phương thức request đến API.
• Sử dụng Annotations để mô tả yêu cầu HTTP.
• Tạo một Retrofit.Builder để khởi tạo các phương thức trong interface đã được định nghĩa.

3. Các Annotations để mô tả yêu cầu HTTP

3.1. Request method

Mỗi phương thức phải có Annotation HTTP cung cấp request method và URL. Có 5 Annotation được tích hợp sẵn: @GET, @POST, @PUT, @DELETE và @HEAD.

@GET("/api/v1/users?sort=desc")
Call<List<User>> getUsers();

3.2. Header manipulation

Chúng ta có thể set thông tin static header bằng cách sử dụng annotation @Header ở mức method.

@Headers({
    "Cache-Control: max-age=640000",
    "Accept: application/vnd.github.v3.full+json",
    "User-Agent: Retrofit-Sample-App"
})
@GET("/api/v1/users?sort=desc")
Call<List<User>> getUsers();

Trong trường hợp thông tin header có thể thay đổi, chúng có thể sử dụng @Header ở mức parameter.

@GET("/api/v1/users?sort=desc")
Call<List<User>> getUsers(@Header("Authorization") String authorization);

Đối với các kết hợp tham số truy vấn phức tạp, có thể sử dụng @HeaderMap.

@GET("/api/v1/users?sort=desc")
Call<List<User>> getUsers(@HeaderMap Map<String, String> headers);

3.3. Url manipulation

URL request có thể được cập nhật tự động bằng cách sử dụng các khối thay thế và tham số trên phương thức.

Chúng ta có thể sử dụng URL 1 cách động dựa vào biến truyền vào, bằng cách sử dụng anotation @Path.

@GET("/api/v1/users/{id}")
Call<User> getUser(@Path("id") int userId);

Chúng ta có thể nối thêm paramater vào sau URL bằng cách sử dụng @Query.

@GET("/api/v1/users?page=1&limit=10")
 
Call<List<User>> getUsers(@Query("page") int page, @Query("limit") int limit);

Đối với các kết hợp tham số truy vấn phức tạp, có thể sử dụng @QueryMap.

@GET("/api/v1/users?page=1&limit=10&sortBy=createdAt&order=desc")
 
Call<List<User>> getUsers(@QueryMap Map<String, String> options);

3.4. Request body

Một đối tượng có thể được chỉ định để sử dụng làm phần thân yêu cầu HTTP với Annotation @Body.

@POST("/api/v1/users")
Call<User> createUser(@Body User user);

3.5. Form encoded and Multipart

Các phương thức cũng có thể được khai báo để gửi dữ liệu được mã hóa và dữ liệu multipart. Dữ liệu được mã hóa theo form được gửi khi @FormUrlEncoded được chỉ định trên phương thức. Mỗi cặp key-value được chú thích bằng @Field chứa tên và đối tượng cung cấp giá trị.

@FormUrlEncoded
@POST("/api/v1/auth")
Call<String> getToken(@Field("username") String username, @Field("password") String password);

Các yêu cầu multipart được sử dụng khi @Multipart xuất hiện trên phương thức. Các phần được khai báo bằng cách sử dụng @Part. @Multipart thường được sử dụng để truyền tải file.

@Multipart
@POST("/api/v1/files/upload")
Call<String> uploadFile(@Part("uploadFile") RequestBody uploadFile, @Part("description") RequestBody description);

4. Ví dụ CRUD Restful Client với Retrofit

4.1. Tạo project

Tạo maven project và khai báo dependency sau trong file pom.xml.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
 
    <groupId>com.maixuanviet</groupId>
    <artifactId>RestfulClientWithRetrofitExample</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>
 
    <name>RestfulClientWithRetrofitExample</name>
    <url>http://maven.apache.org</url>
 
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
        <lombok.version>1.16.20</lombok.version>
    </properties>
 
    <dependencies>
        <!-- https://mvnrepository.com/artifact/com.squareup.retrofit2/retrofit -->
        <dependency>
            <groupId>com.squareup.retrofit2</groupId>
            <artifactId>retrofit</artifactId>
            <version>2.6.0</version>
        </dependency>
 
        <!-- https://mvnrepository.com/artifact/com.squareup.retrofit2/converter-jackson -->
        <dependency>
            <groupId>com.squareup.retrofit2</groupId>
            <artifactId>converter-jackson</artifactId>
            <version>2.6.0</version>
        </dependency>
 
        <!-- https://mvnrepository.com/artifact/com.squareup.retrofit2/converter-gson -->
        <!-- <dependency>
            <groupId>com.squareup.retrofit2</groupId>
            <artifactId>converter-gson</artifactId>
            <version>2.6.0</version>
        </dependency> -->
 
        <!-- https://mvnrepository.com/artifact/org.projectlombok/lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>${lombok.version}</version>
            <scope>provided</scope>
        </dependency>
 
    </dependencies>
</project>

Trong project này, tôi sử dụng thư viện jackson để convert request/ response data giữa client và server.

4.2. Tạo CRUD Restful Client với OkHttp

Trong ví dụ này, chúng ta sẽ gọi lại các Restful API chúng ta đã tạo ở bài viết trước “JWT – Token-based Authentication trong Jersey 2.x“.

Đầu tiên, chúng ta cần gọi API /auth để lấy token và sau đó chúng ta sẽ attach token này vào mỗi request để truy cập resource.

AuthService.java

package com.maixuanviet.service;
 
import okhttp3.ResponseBody;
import retrofit2.Call;
import retrofit2.http.Field;
import retrofit2.http.FormUrlEncoded;
import retrofit2.http.Headers;
import retrofit2.http.POST;
 
public interface AuthService {
 
    @Headers("Accept: application/json; charset=utf-8")
    @FormUrlEncoded
    @POST("auth")
    Call<ResponseBody> getToken(@Field("username") String username, @Field("password") String password);
}

OrderService.java

package com.maixuanviet.service;
 
import com.maixuanviet.model.Order;
 
import okhttp3.ResponseBody;
import retrofit2.Call;
import retrofit2.http.Body;
import retrofit2.http.DELETE;
import retrofit2.http.GET;
import retrofit2.http.Header;
import retrofit2.http.POST;
import retrofit2.http.PUT;
import retrofit2.http.Path;
 
public interface OrderService {
 
    @GET("orders/{id}")
    Call<ResponseBody> getOrder(@Path("id") int id, @Header("Authorization") String authorization);
 
    @POST("orders")
    Call<ResponseBody> createOrder(@Body Order order, @Header("Authorization") String authorization);
 
    @PUT("orders")
    Call<ResponseBody> updateOrder(@Body Order order, @Header("Authorization") String authorization);
 
    @DELETE("orders/{id}")
    Call<ResponseBody> deleteOrder(@Path("id") int id, @Header("Authorization") String authorization);
}

Các method của chúng ta sử dụng Call để nhận kết quả trả về.

• Call : là một invocation của các method trong Retrofit được sử gửi request lên server và nhận kết quả trả về.
• ResponseBody : là kiểu dữ liệu của response về từ server. Do tất cả API của Server trả về là String nên chúng ta sẻ sử dụng ResponseBody. Nếu response trả về là json Order, các bạn có thể sử dụng trực tiếp Call<User>.

Để sử dụng các method này, chúng ta sẽ tạo một Retrofit client:

RetrofitClientCreator.java

package com.maixuanviet.helper;
 
import retrofit2.Retrofit;
import retrofit2.converter.gson.GsonConverterFactory;
import retrofit2.converter.jackson.JacksonConverterFactory;
 
public class RetrofitClientCreator {
 
    public static final String BASE_URL = "http://localhost:8080/RestfulWebServiceExample/rest/";
     
    public static Retrofit getClient() {        
        return new Retrofit.Builder()
                .baseUrl(BASE_URL) //This is the onlt mandatory call on Builder object
                .addConverterFactory(JacksonConverterFactory.create()) // Convertor library used to convert response into POJO
                // .addConverterFactory(GsonConverterFactory.create())
                .build();
    }
}

Tiếp theo chúng ta sẽ sử dụng Retrofit để call các API.

RetrofitClientExample.java

package com.maixuanviet;
 
import java.io.IOException;
 
import com.maixuanviet.helper.RetrofitClientCreator;
import com.maixuanviet.model.Order;
import com.maixuanviet.service.AuthService;
import com.maixuanviet.service.OrderService;
 
import okhttp3.ResponseBody;
import retrofit2.Call;
import retrofit2.Response;
import retrofit2.Retrofit;
 
public class RetrofitClientExample {
 
    private static Retrofit retrofit;
 
    public static void main(String[] args) throws IOException {
        retrofit = RetrofitClientCreator.getClient();
        String token = getToken();
        String authentication = "Bearer " + token;
 
        createOrder(authentication);
        retrieveOrder(authentication);
        updateOrder(authentication);
        deleteOrder(authentication);
    }
 
    private static String getToken() throws IOException {
        // Create an implementation of the API endpoints defined by the service interface
        AuthService authService = retrofit.create(AuthService.class);
 
        // Create an invocation of a Retrofit method that sends a request to a webserver
        // and returns a response.
        Call<ResponseBody> call = authService.getToken("maixuanviet", "maixuanviet");
 
        // Synchronously send the request and return its response
        Response<ResponseBody> response = call.execute();
        String token = response.body().string();
        System.out.println("getToken: " + token);
        return token;
    }
 
    /**
     * @POST http://localhost:8080/RestfulWebServiceExample/rest/orders
     */
    private static void createOrder(String authentication) throws IOException {
        OrderService orderService = retrofit.create(OrderService.class);
        Call<ResponseBody> call = orderService.getOrder(1, authentication);
        Response<ResponseBody> response = call.execute();
        System.out.println("createOrder: " + response.body().string());
    }
 
    /**
     * @GET http://localhost:8080/RestfulWebServiceExample/rest/orders/1
     */
    private static void retrieveOrder(String authentication) throws IOException {
        OrderService orderService = retrofit.create(OrderService.class);
        Call<ResponseBody> call = orderService.createOrder(new Order(), authentication);
        Response<ResponseBody> response = call.execute();
        System.out.println("retrieveOrder: " + response.body().string());
    }
 
    /**
     * @PUT http://localhost:8080/RestfulWebServiceExample/rest/orders
     */
    private static void updateOrder(String authentication) throws IOException {
        OrderService orderService = retrofit.create(OrderService.class);
        Call<ResponseBody> call = orderService.updateOrder(new Order(), authentication);
        Response<ResponseBody> response = call.execute();
        System.out.println("updateOrder: " + response.body().string());
    }
 
    /**
     * @DELETE http://localhost:8080/RestfulWebServiceExample/rest/orders/1
     */
    private static void deleteOrder(String authentication) throws IOException {
        OrderService orderService = retrofit.create(OrderService.class);
        Call<ResponseBody> call = orderService.deleteOrder(1, authentication);
        Response<ResponseBody> response = call.execute();
        System.out.println("deleteOrder: " + response.body().string());
    }
}

Trong ví dụ này, tôi sử dụng phương thức call.execute() để gửi request lên server và nhận kết quả trả về. Phương thức này được thực thi đồng bộ (Synchronous). Nếu bạn muốn gửi request bất đồng bộ, có thể sử dụng phương thức call.enqueue(callback).

4.3. Sử dụng Interceptor với OkHttp

Trong ví dụ trên, ở mỗi phương thức chúng ta đều phải thêm một tham số authentication để gửi lên server. Cách làm này khá là phiền phức. Để giải quyết vấn đề này, chúng ta có thể sử dụng Interceptor, một tính năng đã được hỗ trợ trong OkHttp. Với Retrofit chúng ta cũng có thể sử dụng Interceptor, do nó sử dụng toàn bộ OkHttp như một phần implement của nó.

Bây giờ chúng ta sẽ sử dụng Interceptor để tự động thêm Token vào mỗi request, chúng ta không cần thêm nó một cách thủ công trong từng request. Ví dụ bên dưới sử dụng 2 Interceptor:

• AuthInterceptor : thêm Token vào mỗi request.
• LoggingInterceptor : log trước khi gửi request và sau khi nhận response.

AuthInterceptor.java

package com.maixuanviet.interceptor;
 
import java.io.IOException;
 
import com.maixuanviet.helper.RetrofitClientCreator;
import com.maixuanviet.service.AuthService;
 
import okhttp3.Interceptor;
import okhttp3.Request;
import okhttp3.Response;
import okhttp3.ResponseBody;
import retrofit2.Call;
import retrofit2.Retrofit;
 
public class AuthInterceptor implements Interceptor {
     
    private static String token = null;
 
    @Override
    public Response intercept(Chain chain) throws IOException {
        /*
         * chain.request() returns original request that you can work with(modify,
         * rewrite)
         */
        Request originalRequest = chain.request();
 
        // Here we can rewrite the request
        // We add an Authorization header if the request is not an authorize request and already had a token
        Request authRequest = originalRequest;
        if (!originalRequest.url().toString().contains("/auth") && getToken() != null) {
            authRequest = originalRequest.newBuilder()
                    .header("Authorization", "Bearer " + getToken())
                    .build();
        }
         
        /*
         * chain.proceed(request) is the call which will initiate the HTTP work. This
         * call invokes the request and returns the response as per the request.
         */
        Response response = chain.proceed(authRequest);
         
        // Here we can rewrite/modify the response
         
        return response;
    }
 
    private String getToken() throws IOException {
        if (token != null) {
            return token;
        }
         
        Retrofit retrofit = RetrofitClientCreator.getClientWithInterceptor();
         
        // Create an implementation of the API endpoints defined by the service interface
        AuthService authService = retrofit.create(AuthService.class);
 
        // Create an invocation of a Retrofit method that sends a request to a webserver
        // and returns a response.
        Call<ResponseBody> call = authService.getToken("maixuanviet", "maixuanviet");
 
        // Synchronously send the request and return its response
        retrofit2.Response<ResponseBody> response = call.execute();
        String token = response.body().string();
        System.out.println("getToken: " + token);
        return token;
    }
}

Tương tự chúng ta sẽ tạo LoggingInterceptor
LoggingInterceptor.java

package com.maixuanviet.interceptor;
 
import java.io.IOException;
 
import okhttp3.Interceptor;
import okhttp3.Request;
import okhttp3.Response;
 
public class LoggingInterceptor implements Interceptor {
    @Override
    public Response intercept(Interceptor.Chain chain) throws IOException {
        Request request = chain.request();
 
        long t1 = System.nanoTime();
        System.out.println(
                String.format("Sending request %s on %s%n%s", request.url(), chain.connection(), request.headers()));
 
        Response response = chain.proceed(request);
 
        long t2 = System.nanoTime();
        System.out.println(String.format("Received response for %s in %.1fms%n%s", response.request().url(),
                (t2 - t1) / 1e6d, response.headers()));
 
        return response;
    }
}

Để sử dụng Interceptor, chúng ta cần đăng ký với Client thông qua phương thức addInterceptor() hoặc addNetworkInterceptor(). Chương trình bên dưới, tôi đăng ký AuthInterceptor ở mức Application và LoggingInterceptor cho cả 2 mức Application và Network.

RetrofitClientCreator.java

package com.maixuanviet.helper;
 
import com.maixuanviet.interceptor.AuthInterceptor;
import com.maixuanviet.interceptor.LoggingInterceptor;
 
import okhttp3.OkHttpClient;
import retrofit2.Retrofit;
import retrofit2.converter.jackson.JacksonConverterFactory;
 
public class RetrofitClientCreator {
 
    public static final String BASE_URL = "http://localhost:8080/RestfulWebServiceExample/rest/";
     
    public static Retrofit getClientWithInterceptor() {     
        OkHttpClient okHttpClient = new OkHttpClient.Builder()
                .addInterceptor(new LoggingInterceptor())
                .addInterceptor(new AuthInterceptor())
                .addNetworkInterceptor(new LoggingInterceptor())
                .build();
         
        return new Retrofit.Builder()
                .baseUrl(BASE_URL) //This is the onlt mandatory call on Builder object.
                .client(okHttpClient) //The Htttp client to be used for requests
                .addConverterFactory(JacksonConverterFactory.create()) // Convertor library used to convert response into POJO
                .build();
    }
}

Bây giờ chương trình client của chúng ta, có thể sửa bỏ tham số authentication.

OrderServiceV2.java

package com.maixuanviet.service;
 
import com.maixuanviet.model.Order;
 
import okhttp3.ResponseBody;
import retrofit2.Call;
import retrofit2.http.Body;
import retrofit2.http.DELETE;
import retrofit2.http.GET;
import retrofit2.http.POST;
import retrofit2.http.PUT;
import retrofit2.http.Path;
 
public interface OrderServiceV2 {
 
    @GET("orders/{id}")
    Call<ResponseBody> getOrder(@Path("id") int id);
 
    @POST("orders")
    Call<ResponseBody> createOrder(@Body Order order);
 
    @PUT("orders")
    Call<ResponseBody> updateOrder(@Body Order order);
 
    @DELETE("orders/{id}")
    Call<ResponseBody> deleteOrder(@Path("id") int id);
}

Class Client đơn giản sửa lại như sau:

RetrofitClientWithInterceptorExample.java

package com.maixuanviet;
 
import java.io.IOException;
 
import com.maixuanviet.helper.RetrofitClientCreator;
import com.maixuanviet.model.Order;
import com.maixuanviet.service.OrderServiceV2;
 
import okhttp3.ResponseBody;
import retrofit2.Call;
import retrofit2.Response;
import retrofit2.Retrofit;
 
public class RetrofitClientWithInterceptorExample {
 
    private static Retrofit retrofit;
 
    public static void main(String[] args) throws IOException {
        retrofit = RetrofitClientCreator.getClientWithInterceptor();
        createOrder();
        retrieveOrder();
        updateOrder();
        deleteOrder();
    }
 
    /**
     * @POST http://localhost:8080/RestfulWebServiceExample/rest/orders
     */
    private static void createOrder() throws IOException {
        OrderServiceV2 orderService = retrofit.create(OrderServiceV2.class);
        Call<ResponseBody> call = orderService.getOrder(1);
        Response<ResponseBody> response = call.execute();
        System.out.println("createOrder: " + response.body().string());
    }
 
    /**
     * @GET http://localhost:8080/RestfulWebServiceExample/rest/orders/1
     */
    private static void retrieveOrder() throws IOException {
        OrderServiceV2 orderService = retrofit.create(OrderServiceV2.class);
        Call<ResponseBody> call = orderService.createOrder(new Order());
        Response<ResponseBody> response = call.execute();
        System.out.println("retrieveOrder: " + response.body().string());
    }
 
    /**
     * @PUT http://localhost:8080/RestfulWebServiceExample/rest/orders
     */
    private static void updateOrder() throws IOException {
        OrderServiceV2 orderService = retrofit.create(OrderServiceV2.class);
        Call<ResponseBody> call = orderService.updateOrder(new Order());
        Response<ResponseBody> response = call.execute();
        System.out.println("updateOrder: " + response.body().string());
    }
 
    /**
     * @DELETE http://localhost:8080/RestfulWebServiceExample/rest/orders/1
     */
    private static void deleteOrder() throws IOException {
        OrderServiceV2 orderService = retrofit.create(OrderServiceV2.class);
        Call<ResponseBody> call = orderService.deleteOrder(1);
        Response<ResponseBody> response = call.execute();
        System.out.println("deleteOrder: " + response.body().string());
    }
}

Chạy ứng dụng, các bạn sẽ thấy nó có cùng kết quả với ví dụ đầu tiên. Tuy nhiên, chúng ta không cần quan tâm đến token nữa. Mọi thứ đã được handle trong AuthInterceptor.

Trên đây là những thông tin cơ bản về Retrofit, ngoài ra chúng ta có thể upload, download file khi sử dụng retrofit. Tương tự OkHttp, Retrofit được sử dụng chủ yếu trong các ứng dụng Android để thao tác từ client đến server. Tuy nhiên, chúng ta hoàn toàn có thể sử dụng nó một cách dễ dàng với Rest Client trong ứng dụng java web.