Retrofit — apa itu, HTTP-pustaka dan penggunaan dalam aplikasi

Apa itu Retrofit?

Retrofit adalah pustaka untuk melakukan permintaan HTTP dalam aplikasi Android, dikembangkan oleh perusahaan Square. Ini menyediakan pendekatan deklaratif untuk mendefinisikan REST API melalui antarmuka Java dengan anotasi, yang membuat kode komunikasi jaringan bersih dan dapat diprediksi.

Ide utama Retrofit adalah pengembang mendeskripsikan API sebagai antarmuka dengan metode dan anotasi, dan pustaka secara mandiri menghasilkan implementasi. Pendekatan ini menjamin bahwa semua endpoint telah ditipkan, dan kesalahan dalam URL atau parameter terdeteksi pada tahap kompilasi, bukan saat runtime.

Retrofit mendukung semua metode HTTP populer dan format data. Pustaka ini aktif dipelihara oleh Square dan komunitas: versi baru dirilis secara teratur, dan versi saat ini 2.11 mencakup dukungan untuk Java 17 dan Kotlin 2.0. Retrofit tetap menjadi HTTP-klien paling populer untuk Android.

Retrofit bekerja di atas OkHttp — HTTP-klien efisien juga dari Square. Kombinasi ini menyediakan caching, intersepsi permintaan, dan manajemen koneksi pada tingkat protokol transport. Pustaka mendukung panggilan sinkron dan asinkron.

Sejak rilis pertama pada tahun 2013, Retrofit telah melalui beberapa pembaruan besar. Versi saat ini Retrofit 2 telah ditulis ulang sepenuhnya dengan mempertimbangkan pengalaman dari versi pertama dan menawarkan sistem konverter dan adaptor yang lebih fleksibel untuk asinkronisitas.

Arsitektur Retrofit mengikuti prinsip pemisahan tanggung jawab: antarmuka hanya mendefinisikan kontrak API, konverter bertanggung jawab atas serialisasi, dan adaptor mengelola asinkronisitas. Ini memungkinkan penggantian komponen apa pun tanpa mengubah kode lainnya. Misalnya, dapat beralih dari Gson ke Moshi tanpa mengubah definisi endpoint.

Fitur utama Retrofit

Retrofit menyediakan serangkaian fungsi yang mencakup hampir semua skenario komunikasi jaringan dalam aplikasi seluler. Keuntungan utamanya adalah gaya deklaratif dalam mendefinisikan API.

Anotasi deklaratif endpoint

Anotasi @GET, @POST, @PUT, @PATCH, @DELETE dan @HTTP memungkinkan mendefinisikan metode HTTP dan template URL langsung di antarmuka. Parameter jalur diatur melalui @Path, parameter query melalui @Query, dan body permintaan melalui @Body. Pendekatan ini membuat lapisan API aplikasi sepenuhnya ditipkan.

Konverter untuk serialisasi

Konverter mengubah respons HTTP menjadi objek Java dan sebaliknya. Retrofit mendukung Gson, Moshi, Jackson, Protobuf dan Wire. Pengembang menghubungkan konverter yang diperlukan melalui Converter.Factory, dan pustaka secara otomatis menerapkannya ke semua permintaan dan respons.

Adaptor untuk asinkronisitas

Adaptor CallAdapter memungkinkan mengubah tipe nilai kembali dari metode API. Alih-alih Call standar, dapat menggunakan Observable untuk RxJava, Deferred untuk korutin Kotlin atau LiveData. Ini mengintegrasikan permintaan jaringan dengan arsitektur aplikasi yang dipilih.

URL dan header dinamis

URL dinamis diatur melalui anotasi @Url, memungkinkan penerusan endpoint saat runtime. Header dapat ditentukan secara statis melalui @Headers atau secara dinamis melalui parameter @Header. Untuk header global semua permintaan, digunakan interceptor OkHttp yang menambahkan header ke setiap permintaan keluar.

Bagaimana cara kerja Retrofit?

Retrofit bekerja dalam tiga tahap: mendefinisikan antarmuka API, membuat instance Retrofit, dan menjalankan permintaan. Pustaka menghasilkan implementasi antarmuka saat runtime berdasarkan anotasi dan konverter.

Siklus hidup permintaan

Ketika metode API dipanggil, Retrofit membuat objek Request berdasarkan anotasi dan argumen. Permintaan diteruskan ke OkHttp untuk dieksekusi. Setelah menerima respons, pustaka mengirimkannya ke Converter.Factory untuk diubah menjadi tipe yang diperlukan. CallAdapter membungkus hasilnya dalam pembungkus asinkron. Setiap tahap dapat disesuaikan.

interface ApiService {
    @GET("users/{id}")
    suspend fun getUser(@Path("id") id: Int): User
}

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .build()

val api = retrofit.create(ApiService::class.java)

Instalasi dan konfigurasi Retrofit

Instalasi Retrofit dilakukan melalui Gradle — sistem build standar Android. Pustaka didistribusikan melalui Maven Central dan memerlukan penambahan beberapa dependensi di build.gradle proyek.

Menambahkan dependensi

Dalam file build.gradle (tingkat modul) tambahkan dependensi untuk Retrofit, konverter Gson, dan OkHttp. Versi pustaka disarankan untuk ditempatkan dalam variabel di build.gradle root untuk manajemen terpusat. Retrofit 2 membutuhkan minimal Android API 21.

dependencies {
    implementation "com.squareup.retrofit2:retrofit:2.11.0"
    implementation "com.squareup.retrofit2:converter-gson:2.11.0"
    implementation "com.squareup.okhttp3:okhttp:4.12.0"
    implementation "com.squareup.okhttp3:logging-interceptor:4.12.0"
}

Membuat instance Retrofit

Instance Retrofit dibuat melalui Builder. Parameter wajib: baseUrl dan ConverterFactory. Disarankan menggunakan singleton untuk Retrofit dan OkHttpClient untuk menghindari pembuatan koneksi yang berlebihan. Menambahkan logging-interceptor menyederhanakan debugging permintaan jaringan selama pengembangan.

Untuk proyek Kotlin, disarankan menggunakan fungsi suspend di antarmuka API alih-alih tipe Call. Ini menyederhanakan kode dan memungkinkan penggunaan konkurensi terstruktur dari korutin. Saat beralih dari Call ke suspend, cukup mengubah tipe kembali di antarmuka — kode lainnya menyesuaikan secara otomatis.

Contoh penggunaan Retrofit

Contoh di bawah menunjukkan skenario tipikal bekerja dengan Retrofit dalam aplikasi Android: dari permintaan GET sederhana hingga mengunggah file ke server.

Permintaan GET dengan parameter query

Permintaan GET sederhana dengan parameter query — operasi dasar. Anotasi @Query menambahkan parameter secara otomatis ke URL, dan fungsi suspend memungkinkan memanggil permintaan dari korutin tanpa memblokir thread utama.

interface UserApi {
    @GET("users")
    suspend fun getUsers(
        @Query("page") page: Int,
        @Query("limit") limit: Int = 20
    ): List<User>
}

val users = api.getUsers(page = 1)

Permintaan POST dengan body JSON

Permintaan POST dengan body JSON menggunakan anotasi @Body untuk mengirim objek. GsonConverterFactory secara otomatis menserialisasi objek User menjadi JSON. Korutin Kotlin memastikan eksekusi permintaan di latar belakang tanpa antarmuka Callback.

interface UserApi {
    @POST("users")
    suspend fun createUser(@Body user: User): User
}

val user = User(name = "Anna Ivanova", email = "anna@example.com")
val created = api.createUser(user)

Mengunggah file melalui Multipart

Anotasi @Multipart dengan @Part memungkinkan mengunggah file ke server. Retrofit secara otomatis membuat permintaan multipart dengan header yang diperlukan. OkHttp mengelola kemajuan unggahan melalui RequestBody, memungkinkan menampilkan indikator kepada pengguna.

interface FileApi {
    @Multipart
    @POST("upload")
    suspend fun uploadImage(
        @Part file: MultipartBody.Part
    ): UploadResponse
}

val body = "image.jpg".toRequestBody("image/jpeg".toMediaTypeOrNull())
val part = MultipartBody.Part.createFormData("file", "image.jpg", body)

Penanganan kesalahan dan interceptor di Retrofit

Penanganan kesalahan di Retrofit didasarkan pada kombinasi mekanisme OkHttp dan korutin Kotlin. Interceptor OkHttp memungkinkan mencatat permintaan, menambahkan header otentikasi, dan menangani kesalahan sebelum mencapai kode aplikasi.

Untuk penanganan kesalahan terpusat, sering dibuat pembungkus di sekitar panggilan API dalam bentuk sealed class Result. Kelas semacam itu berisi dua turunan: Success dengan data dan Error dengan pengecualian. ViewModel menerima hasil yang terunifikasi dan dapat menampilkan status antarmuka pengguna yang sesuai tanpa menduplikasi kode penanganan kesalahan di setiap fungsi.

Interceptor terdiri dari dua jenis: interceptor aplikasi memodifikasi permintaan sebelum dikirim ke server, dan interceptor jaringan bekerja dengan respons setelah diterima. Misalnya, interceptor dapat secara otomatis memperbarui token akses saat menerima 401 dan mengulangi permintaan dengan token baru tanpa campur tangan pengembang.

Mencatat permintaan melalui Interceptor

Interceptor pencatatan HttpLoggingInterceptor — alat yang sangat diperlukan saat debugging permintaan jaringan. Ini menampilkan di Logcat metode permintaan, URL, header, body, dan kode respons. Tingkat pencatatan dapat dikonfigurasi: BASIC untuk informasi minimal, HEADERS untuk header, atau BODY untuk konten lengkap. Dalam produksi, disarankan menggunakan BASIC atau menonaktifkan pencatatan sepenuhnya.

Interceptor di OkHttp dibagi menjadi dua jenis: interceptor aplikasi untuk memodifikasi permintaan dan interceptor jaringan untuk bekerja dengan data jaringan mentah. Interceptor pencatatan secara otomatis menampilkan detail permintaan dan respons di Logcat.

Penanganan kesalahan pada tingkat korutin dilakukan melalui try-catch di sekitar panggilan fungsi suspend. Retrofit mengembalikan kesalahan dalam bentuk HttpException untuk kode 4xx dan 5xx, UnknownHostException saat tidak ada jaringan, dan SocketTimeoutException saat melampaui batas waktu. Disarankan menggunakan sealed class Result untuk penanganan terunifikasi.