Retrofit: apa itu, fitur klien HTTP Android

Apa itu Retrofit?

Retrofit — adalah pustaka untuk interaksi bertipe dengan REST API pada platform Android, dikembangkan oleh perusahaan Square. Pustaka ini menyediakan cara deklaratif untuk mendeskripsikan permintaan HTTP melalui antarmuka Java atau Kotlin dengan anotasi, sepenuhnya membebaskan pengembang dari parsing JSON manual dan pengelolaan koneksi HTTP.

Pustaka ini muncul pada tahun 2013 sebagai alternatif untuk solusi rumit seperti AsyncTask dan HttpURLConnection. Hingga tahun 2025, Retrofit tetap menjadi standar de facto untuk komunikasi jaringan di aplikasi Android berkat kesederhanaan dan keamanan tipe. Menurut survei JetBrains Developer Ecosystem 2024, Retrofit digunakan oleh lebih dari 65% pengembang Android di proyek komersial.

Perbedaan utama Retrofit dari alternatif — pendekatan deklaratif: pengembang mendeskripsikan apa yang harus dilakukan (endpoint mana yang dipanggil, parameter apa yang dikirim), bukan bagaimana melakukannya (bagaimana membuka koneksi, bagaimana membaca InputStream, bagaimana mem-parse JSON). Ini mengurangi jumlah kode boilerplate sebesar 60–70% dibandingkan dengan penggunaan manual HttpURLConnection.

Bagaimana Retrofit bekerja

Prinsip kerja Retrofit didasarkan pada proxy dinamis Java. Ketika pengembang memanggil metode antarmuka yang ditandai dengan anotasi, Retrofit melalui mekanisme Proxy.newProxyInstance mencegat panggilan dan mengubahnya menjadi permintaan HTTP. Seluruh proses terjadi di runtime tanpa pembuatan kode pada tahap kompilasi.

Saat membuat instance Retrofit.Builder, URL dasar dan pabrik konverter ditentukan. Builder mengonfigurasi OkHttpClient — menetapkan timeout, interceptor, kumpulan koneksi, dan cache. Metode create(Class) menghasilkan implementasi antarmuka, mengembalikan objek proxy yang dapat dipanggil seperti kelas biasa.

Rantai eksekusi permintaan terlihat seperti ini: anotasi mengekstrak metode HTTP, parameter dimasukkan ke dalam URL atau body permintaan, konverter men-serialisasi body, OkHttp menjalankan permintaan, konverter men-deserialisasi respons, hasilnya dikembalikan dalam tipe yang ditentukan. Setiap tahap terisolasi dan dapat diganti dengan implementasi kustom, misalnya mengganti OkHttpClient dengan MockWebServer untuk pengujian atau mengganti konverter saat perubahan API.

Fitur penting — Retrofit tidak mendukung streaming data secara langsung. Untuk streaming, OkHttp ResponseBody digunakan sebagai tipe pengembalian metode antarmuka. Retrofit juga tidak mengelola pembatalan permintaan secara otomatis — untuk membatalkan, perlu menyimpan referensi ke Call dan memanggil cancel(). Di Kotlin dengan fungsi suspend, pembatalan permintaan terjadi secara otomatis saat pembatalan coroutine induk.

Siklus hidup objek Call

Call<T> — adalah objek yang mewakili satu permintaan HTTP. Setelah eksekusi (execute atau enqueue), Call tidak dapat digunakan kembali — untuk permintaan berulang, perlu membuat Call baru melalui pemanggilan metode antarmuka. Ini melindungi dari pengiriman tidak sengaja permintaan yang sama dua kali, yang dapat menyebabkan duplikasi operasi di server.

Di Kotlin, alih-alih Call, digunakan fungsi suspend yang secara otomatis mengelola siklus hidup permintaan. Retrofit sendiri mengalihkan eksekusi ke Dispatchers.IO dan mengembalikan hasil ke coroutine. Ini mempersingkat kode sebesar 30–40% dibandingkan dengan versi Call dan Callback.

Anotasi Retrofit untuk metode HTTP

Anotasi — adalah mekanisme utama konfigurasi permintaan HTTP di Retrofit. Setiap anotasi sesuai dengan metode HTTP standar dan menerima jalur relatif ke endpoint. Retrofit mendukung GET, POST, PUT, DELETE, PATCH, HEAD, dan OPTIONS.

Anotasi parameter permintaan

@Path mengganti nilai di segmen URL: @Path(id) Int id mengganti {id} di jalur. @Query menambahkan parameter query: @Query(page) Int page berubah menjadi ?page=5. @Body mengirimkan objek di body permintaan dengan serialisasi otomatis melalui konverter yang dipilih. @Header dan @Headers mengelola header HTTP — statis atau dinamis.

Dengan menggabungkan anotasi ini, endpoint REST apa pun dapat dideskripsikan. Misalnya, untuk endpoint POST /api/users/{id}/posts?limit=10 diperlukan @POST, @Path untuk id, @Query untuk limit, dan @Body untuk objek yang dikirimkan. Retrofit secara otomatis akan menyusun permintaan HTTP yang benar. Selain itu, didukung @Url (URL dinamis), @Field (body form-encoded), @Part dan @PartMap untuk permintaan multipart dengan file.

Contoh kode Retrofit di Kotlin

Mari kita lihat contoh praktis — antarmuka untuk API GitHub. Dibuat antarmuka Kotlin dengan metode untuk mendapatkan daftar repositori. Data class Repo mendeskripsikan struktur respons JSON.

data class Repo(
    val name: String,
    val description: String?,
    val stargazersCount: Int,
    val forksCount: Int
)

interface GitHubApi {
    @GET("users/{user}/repos")
    suspend fun getRepos(
        @Path("user") user: String,
        @Query("sort") sort: String = "updated"
    ): List<Repo>
}

Setelah mendeskripsikan antarmuka, dibuat instance Retrofit melalui Builder. URL dasar, konverter, dan OkHttpClient dikonfigurasi sekali dan digunakan kembali melalui dependency injection.

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.github.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .client(OkHttpClient.Builder()
        .connectTimeout(30, TimeUnit.SECONDS)
        .build())
    .build()

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

Pemrosesan respons dengan pembungkus Response

Untuk pemrosesan status HTTP yang fleksibel, gunakan pembungkus Response<T>. Ini memberikan akses ke kode respons, header, dan body, tanpa melempar pengecualian pada kesalahan 4xx dan 5xx. Ini memungkinkan pemrosesan 404 dan 500 tanpa try-catch.

interface GitHubApi {
    @GET("users/{user}/repos")
    suspend fun getRepos(
        @Path("user") user: String
    ): Response<List<Repo>>
}

val response = api.getRepos("octocat")
if (response.isSuccessful) {
    println(response.body()?.size)
} else {
    Log.e("API", "Error: ${response.code()}")
}

Konverter dan serialisasi di Retrofit

Konverter — adalah komponen Retrofit yang bertanggung jawab untuk mengubah objek menjadi body HTTP dan sebaliknya. Retrofit tidak menyematkan serialisasi ke dalam inti — sebagai gantinya, pendekatan modular digunakan melalui Converter.Factory, memungkinkan menghubungkan pustaka serialisasi apa pun.

Konverter paling populer — GsonConverterFactory dari Google berdasarkan pustaka Gson. Cocok untuk sebagian besar proyek, mendukung TypeAdapter dan JsonDeserializer kustom. Namun, Gson menggunakan refleksi dan tidak memperhitungkan null safety Kotlin, yang dapat menyebabkan NPE pada bidang null yang tidak terduga.

Alternatif — MoshiConverterFactory dari Square: lebih ketat terhadap tipe, dengan dukungan Kotlin yang lebih baik (null safety, default values) dan tanpa refleksi. Untuk proyek Kotlin murni, optimal — Kotlinx Serialization Converter, yang bekerja pada anotasi @Serializable pada tahap kompilasi. Tidak menggunakan refleksi, mendukung sealed class, default values, dan multiplatform.

Pilihan konverter memengaruhi kinerja dan keamanan tipe. Gson tanpa konfigurasi kustom dapat men-deserialisasi null ke bidang non-null Kotlin, menyebabkan NPE saat diakses. Moshi memecahkan masalah ini melalui anotasi @Json(name) dan failOnUnknown. Kotlinx Serialization adalah yang paling aman — menghasilkan kode pada tahap kompilasi, sepenuhnya menghilangkan kesalahan tipe runtime.

Kesalahan umum saat bekerja dengan Retrofit

Tidak adanya penanganan kesalahan HTTP di fungsi suspend — masalah paling umum. Jika server mengembalikan 4xx atau 5xx, Retrofit melempar HttpException. Tanpa try-catch, aplikasi akan crash. Penggunaan Response<T> sebagai tipe pengembalian memecahkan masalah ini, memungkinkan pemeriksaan isSuccessful sebelum mengakses body.

Konfigurasi cache yang salah menyebabkan lalu lintas berlebihan. Retrofit tidak menyimpan cache respons sendiri — tugas ini diselesaikan oleh OkHttpClient melalui Cache. Tanpa cache, setiap permintaan dijalankan sepenuhnya, bahkan ketika data tidak berubah. Menambahkan Cache sebesar 10 MB di OkHttpClient mengurangi lalu lintas sebesar 40–60% pada permintaan berulang untuk informasi yang sama.

Membuat Retrofit untuk setiap permintaan — kesalahan umum pemula. Retrofit.Builder adalah operasi intensif sumber daya yang mencakup pembuatan kelas proxy di runtime. Praktik yang benar — membuat satu instance Retrofit dan menggunakannya kembali melalui framework DI. Hilt, Koin, atau Dagger menyediakan instance singleton Retrofit untuk seluruh aplikasi, menghemat memori dan mempercepat permintaan.

Mengabaikan Interceptor untuk otorisasi — masalah keempat. Alih-alih menambahkan header Authorization secara manual di setiap panggilan, konfigurasikan Interceptor global di OkHttpClient. Interceptor mencegat setiap permintaan, menambahkan token Bearer, dan Authenticator memproses respons 401, memperbarui token dan mengulangi permintaan secara otomatis. Ini memusatkan logika autentikasi.