External API Call Basics

Önce kavramları sadeleştirelim

External API konusunu iyi anlamak için önce konuşacağımız kelimeleri netleştirelim. Bu kavramlar sadece teknik terim değil; kodun nerede güvenli, nerede kırılgan olacağını belirleyen tasarım kararlarıdır.

External API çağrısı neden ayrı bir konu?

Çünkü external API çağrısında artık sadece kendi kodumuzun doğruluğuna güvenmeyiz; network, karşı servis, authentication, latency ve hata formatı da iş akışının parçası olur.

Bir Java method'u çağırdığımızda her şey aynı process içinde gerçekleşir. Method yavaşsa profiler ile bakabiliriz, exception atarsa stack trace görürüz, refactor etmek istersek kod bizdedir. External API çağrısında ise çağırdığımız sistem çoğu zaman başka bir ekip, başka bir deployment, başka bir network ve başka bir release takvimi tarafından yönetilir. Bu yüzden external API çağrısı uygulama içinde küçük bir satır gibi görünse de aslında sistemler arası bir sınırdır.

Senior geliştirici için kritik fark şudur: external servis çağrısı başarılı olduğunda değil, başarısız olduğunda tasarımın kalitesi ortaya çıkar. Karşı servis hiç cevap vermezse ne olur? 2 saniye mi bekleriz, 30 saniye mi? 503 geldiğinde tekrar dener miyiz? 400 geldiğinde kullanıcıya ne döneriz? Bu çağrı sırasında DB transaction açık mı kalır? Log'da hangi correlation id ile takip ederiz? Bu sorular net değilse client kodu production'da kırılgan hale gelir.

RestTemplate / WebClient kullanımı

Spring tarafında external HTTP çağrısı için en sık iki isimle karşılaşırız: RestTemplate ve WebClient. İkisi de HTTP çağrısı yapar; fakat tasarım dili, konfigürasyon esnekliği ve modern Spring ekosistemindeki konumları farklıdır.

RestTemplate klasik blocking modelle çalışır. Bir request gönderilir ve o request'in cevabı gelene kadar çağıran thread bekler. Bu yaklaşım özellikle eski Spring projelerinde çok yaygındır ve okunması kolaydır. Ancak yeni projelerde WebClient daha modern bir seçenek olarak öne çıkar. WebClient reactive altyapıdan gelir; ama bu, onu sadece WebFlux projelerinde kullanabiliriz demek değildir. Spring MVC uygulamasında da external client yazarken WebClient kullanılabilir.

// URL kodun içine gömülü, timeout yok, hata ayrımı yok
FraudResponse response = restTemplate.postForObject(
    "http://fraud-service/fraud/check",
    request,
    FraudResponse.class
);

Bu kod demo ortamında çalışabilir; ama production için eksikleri çoktur. URL değişirse kod değişir, karşı servis cevap vermezse ne kadar bekleneceği belirsizdir, 4xx ve 5xx aynı şekilde ele alınabilir ve domain servis bu teknik detaylarla kirlenebilir. Bizim hedefimiz bu çağrıyı ayrı bir client sınıfına almak ve davranışını configuration ile yönetmektir.

HTTP client configuration

External servis URL'ini, timeout değerini, retry sayısını ve aktif/pasif davranışını kodun içine gömmeyiz. Bunlar ortamdan ortama değişebilen configuration değerleridir.

Dev ortamında fraud servisi bir WireMock veya lokal mock olabilir. Test ortamında sandbox endpoint kullanılabilir. Production'da gerçek fraud servisine gidilir. Aynı şekilde timeout değerleri de ortam ve servis kritikliğine göre değişebilir. Kodun içine http://localhost:9090 yazmak, bugünün hızlı çözümünü yarının deployment problemine dönüştürür.

Spring Boot'ta bu değerleri yönetmenin en temiz yollarından biri @ConfigurationProperties kullanmaktır. Böylece configuration string string okunmaz; tipli, gruplanmış ve test edilebilir bir modele dönüşür.

minibank:
  integrations:
    fraud:
      enabled: true
      base-url: http://localhost:9090
      connect-timeout-ms: 1000
      response-timeout-ms: 2000
      retry-count: 2

@ConfigurationProperties(prefix = "minibank.integrations.fraud")
public record FraudClientProperties(
    boolean enabled,
    String baseUrl,
    int connectTimeoutMs,
    int responseTimeoutMs,
    int retryCount
) { }

Timeout set etme

Timeout, external API çağrısının en temel güvenlik kemeridir. Timeout yoksa sistemin ne kadar bekleyeceğini karşı servis belirler; bu production için kabul edilebilir bir durum değildir.

Timeout sadece “kullanıcı çok beklemesin” konusu değildir. Bir HTTP isteği işlendiği sırada thread, memory, connection ve bazen DB transaction kaynakları kullanılır. Karşı servis cevap vermezse bu kaynaklar beklemeye devam eder. Trafik arttığında birkaç yavaş external çağrı, bütün uygulamanın cevap veremez hale gelmesine yol açabilir.

@Bean
WebClient fraudWebClient(FraudClientProperties properties) {
    HttpClient httpClient = HttpClient.create()
        .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, properties.connectTimeoutMs())
        .responseTimeout(Duration.ofMillis(properties.responseTimeoutMs()));

    return WebClient.builder()
        .baseUrl(properties.baseUrl())
        .clientConnector(new ReactorClientHttpConnector(httpClient))
        .build();
}

Basic retry

Retry, geçici hatalarda işe yarayabilir; fakat yanlış kullanılırsa problemi çözmek yerine büyütür.

Bir external servis 503 döndüğünde birkaç yüz milisaniye sonra tekrar denemek mantıklı olabilir. Çünkü servis kısa süreli yoğunluk yaşıyor olabilir. Fakat istek 400 Bad Request dönüyorsa aynı isteği tekrar göndermek sonucu değiştirmez. Hatalı IBAN, eksik token veya geçersiz müşteri numarası retry ile düzelmez.

Retry kararında bir diğer kritik konu idempotency'dir. Bir bakiye sorgulama isteğini tekrar etmek genellikle güvenlidir. Ama para transferi isteği idempotent tasarlanmamışsa aynı request'in tekrar gönderilmesi çift işlem riski doğurabilir. Bu yüzden retry sadece teknik değil, domain kararıdır.

return fraudWebClient.post()
    .uri("/fraud/check")
    .bodyValue(request)
    .retrieve()
    .bodyToMono(FraudCheckResult.class)
    .timeout(Duration.ofMillis(properties.responseTimeoutMs()))
    .retryWhen(Retry.fixedDelay(properties.retryCount(), Duration.ofMillis(200))
        .filter(this::isRetryableFailure))
    .block();

Error mapping: teknik hatayı domain diline çevirmek

External servis hatasını doğrudan controller'a veya kullanıcıya taşımayız. Client katmanı teknik cevabı anlamlandırır ve uygulamanın anlayacağı exception'a çevirir.

Fraud servisi 404, 409, 500 veya timeout dönebilir. Bu cevapların hepsi MiniBank domain'i için aynı anlama gelmez. Bazıları “istek geçersiz”, bazıları “servis geçici olarak kullanılamıyor”, bazıları “risk değerlendirmesi yapılamadı” anlamına gelebilir. Eğer client bu ayrımı yapmazsa service katmanı HTTP detaylarını bilmek zorunda kalır.

.retrieve()
.onStatus(HttpStatusCode::is4xxClientError, response ->
    Mono.error(new FraudRequestRejectedException("Fraud request is not valid")))
.onStatus(HttpStatusCode::is5xxServerError, response ->
    Mono.error(new FraudServiceUnavailableException("Fraud service is temporarily unavailable")))

External call transaction içinde mi olmalı?

Çoğu durumda external API çağrısını DB transaction'ı açıkken yapmak istemeyiz. Çünkü network beklerken database kaynaklarını da bekletmiş oluruz.

Bir transaction başladığında uygulama database connection alır ve bazı işlemlerde lock oluşabilir. Bu sırada external servis çağrısı yaparsak, karşı servisin yavaşlığı bizim database kaynaklarımızı da gereksiz yere meşgul eder. Transfer gibi kritik bir akışta doğru tasarım genellikle şudur: external karar çağrılarını transaction başlamadan yap, transaction içinde sadece veritabanı tutarlılığı gerektiren kısa bölümü çalıştır.

public void transfer(TransferRequest request) {
    fraudCheckClient.check(request.fromIban(), request.toIban(), request.amount());
    transferTransactionService.executeTransfer(request);
}

@Transactional
public void executeTransfer(TransferRequest request) {
    // Sadece DB tutarlılığı gerektiren kısa bölüm burada çalışır.
}

Bu modülden akılda kalması gerekenler