Android Retrofit ile REST API Entegrasyonu: Pratik İpuçları ve Kontrol Listesi

Android uygulamalarında REST API entegrasyonu, modern mobil geliştirmenin temel taşlarından biridir. Retrofit, Square tarafından geliştirilen ve tip güvenliği sağlayan popüler bir HTTP istemcisidir. Bu yazıda, Retrofit'i kullanarak API çağrılarınızı nasıl daha güvenilir, okunabilir ve performanslı hale getireceğinizi pratik ipuçları ve kontrol listesi eşliğinde ele alıyoruz.

Retrofit Kurulumu ve Temel Yapılandırma

Projenize Retrofit'i eklemek için build.gradle dosyasına aşağıdaki bağımlılıkları ekleyin:

dependencies {
    implementation 'com.squareup.retrofit2:retrofit:2.9.0'
    implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
    implementation 'com.squareup.okhttp3:logging-interceptor:4.12.0'
}

Temel bir Retrofit örneği oluşturmak için bir arayüz (interface) tanımlayın:

public interface ApiService {
    @GET("users")
    Call> getUsers();
}

Ardından Retrofit.Builder ile bir örnek oluşturun:

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

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

Pratik İpuçları ve Kontrol Listesi

1. Logging Interceptor Kullanarak Hata Ayıklama

Geliştirme aşamasında HTTP istek ve yanıtlarını görmek için HttpLoggingInterceptor ekleyin. Bu, hataları hızlıca tespit etmenizi sağlar.

• Interceptor'ı OkHttpClient'a ekleyin ve log seviyesini BODY olarak ayarlayın.
• Canlı ortamda log seviyesini NONE yapmayı unutmayın.
• Örnek kod:

HttpLoggingInterceptor logging = new HttpLoggingInterceptor();
logging.setLevel(HttpLoggingInterceptor.Level.BODY);
OkHttpClient client = new OkHttpClient.Builder()
        .addInterceptor(logging)
        .build();

2. Token Yönetimi ve Oturum

Kullanıcı oturumu için genellikle JWT token kullanılır. Her isteğe token eklemek için bir interceptor yazın. Daha fazla bilgi için Backend API'lerde JWT Token Yönetimi yazımıza göz atabilirsiniz.

• Token'ı SharedPreferences veya EncryptedSharedPreferences'te saklayın.
• Interceptor içinde isteğe Authorization: Bearer {token} header'ı ekleyin.
• Token süresi dolduğunda refresh token mekanizması kurun.

3. Hata Yönetimi ve Geri Bildirim

API'den gelen hataları kullanıcıya anlamlı bir şekilde iletin. Retrofit'te Call nesnesi hata durumunda onFailure veya başarısız yanıt döner.

• onResponse içinde response.isSuccessful() kontrolü yapın.
• Başarısız yanıtlarda response.code() ve response.errorBody() ile hata mesajını işleyin.
• Network hatası (IOException) durumunda kullanıcıya bağlantı sorunu olduğunu bildirin.
• Özel hata nesneleri oluşturmak için Converter.Factory kullanabilirsiniz.

4. Pagination, Filtering ve Sorting

Büyük veri kümelerini listelemek için sunucu tarafında sayfalama kullanılır. Retrofit ile sorgu parametrelerini dinamik olarak ekleyin. Daha detaylı bilgi için REST API'lerde Pagination, Filtering ve Sorting rehberimize bakın.

• @Query anotasyonu ile parametreleri ekleyin: @GET("items") Call> getItems(@Query("page") int page, @Query("limit") int limit);
• ScrollListener ile sayfa sonuna gelindiğinde yeni istek atın.
• Sunucu tarafında limit koyarak performansı artırın.

5. Rate Limiting ve Güvenlik

API'yi aşırı yüklememek için istemci tarafında da throttle uygulayın. Sunucu tarafı rate limiting hakkında daha fazla bilgi için REST API Rate Limiting'de Fixed Window vs Token Bucket yazısını okuyabilirsiniz.

• Kullanıcı eylemleri arasında minimum bekleme süresi koyun (örneğin, butona tekrar basma).
• Interceptor ile istek sayısını sayaçla kontrol edin.
• 429 Too Many Requests yanıtı alındığında yeniden deneme (retry) mekanizması kurun.

6. Singleton Pattern ile Retrofit Örneği Yönetimi

Her aktivite veya fragment için yeni bir Retrofit örneği oluşturmak yerine tek bir örnek kullanın.

• Application sınıfında veya DI kapsayıcıda (Dagger/Hilt) tek bir örnek oluşturun.
• OkHttpClient ve ConverterFactory'yi yeniden kullanarak bellek tüketimini azaltın.
• Hilt kullanıyorsanız @Singleton anotasyonu ile sağlayın.

7. LiveData veya Coroutines ile Entegrasyon

Retrofit çağrılarınızı modern Android mimarisi bileşenleriyle uyumlu hale getirin. Kotlin kullanıyorsanız Coroutines ile daha temiz bir yapı kurun.

• Retrofit'in Call yerine suspend fonksiyonlar kullanın: @GET("users") suspend fun getUsers(): List
• ViewModel içinde viewModelScope ile çağrıyı başlatın.
• Yanıtı StateFlow veya LiveData olarak expose edin.

Sık Yapılan Hatalar ve Dikkat Edilmesi Gerekenler

• Base URL'yi trailing slash ile bitirmek: Retrofit base URL'de slash ile bitmeli, endpoint'ler ise slash ile başlamamalıdır.
• ConverterFactory unutmak: GsonConverterFactory eklenmezse dönüşüm hatası alırsınız.
• Interceptor sırası: Interceptor'lar eklenme sırasına göre çalışır; token ekleme interceptor'ı logging'den önce gelmeli.
• UI thread'de network çağrısı: Retrofit varsayılan olarak arka planda çalışır; ancak enqueue() kullanmazsanız ana thread'i bloke edebilirsiniz.

Bu kontrol listesini uygulayarak Android projelerinizde Retrofit entegrasyonunu sorunsuz ve verimli hale getirebilirsiniz. Unutmayın, iyi yapılandırılmış bir API katmanı uygulamanızın sürdürülebilirliğini ve kullanıcı deneyimini doğrudan etkiler.

Sık Sorulan Sorular

Retrofit nedir ve neden kullanmalıyım?

Retrofit, Android için Square tarafından geliştirilen tip güvenli bir HTTP istemcisidir. API çağrılarını kolaylaştırır, veri dönüşümünü otomatikleştirir ve hata yönetimini basitleştirir. Performans ve okunabilirlik açısından manuel implementasyonlara göre daha avantajlıdır.

Retrofit'te interceptor nasıl eklenir?

Interceptor eklemek için bir OkHttpClient oluşturup addInterceptor() metoduyla interceptor'ları ekleyin. Ardından bu client'ı Retrofit.Builder üzerinden set edin. Örneğin, logging interceptor için HttpLoggingInterceptor kullanabilirsiniz.

Retrofit'te token nasıl yönetilir?

Token yönetimi için bir interceptor yazabilirsiniz. Interceptor içinde SharedPreferences'tan token'ı alıp isteğin header'ına ekleyin. Token süresi dolduğunda refresh token kullanarak yenileyin.

Retrofit ile hata yönetimi nasıl yapılır?

Retrofit'te onResponse ve onFailure callback'lerini kullanın. Başarısız yanıtlarda response.isSuccessful() kontrolü yaparak hata kodunu ve body'sini işleyin. Network hatası durumunda kullanıcıya bağlantı sorunu olduğunu bildirin.

Retrofit'te coroutines kullanılabilir mi?

Evet, Retrofit 2.6.0 ve üstü sürümlerde suspend fonksiyonları destekler. Bu sayede Callback yerine daha okunabilir ve asenkron kod yazabilirsiniz. ViewModel'de viewModelScope ile çağrıyı başlatmanız önerilir.