API Türleri: REST, GraphQL, RPC ve Webhook
Her API stilinin güçlü olduğu senaryo; sözleşme, sürümleme, hata modeli ve olay tabanlı iletişim.
API, iki sistemin anlaştığı sözleşmedir. Doğru stil seçimi, istemcinin ihtiyacına ve verinin şekline bağlıdır; moda değil, uygunluk belirler.
REST
Kaynakları URL ile adresleyen, HTTP fiillerini (GET, POST, PUT, DELETE) kullanan yaygın stildir. Önbelleklenebilir, anlaşılır, geniş araç desteği vardır.
- Uygun: kaynak odaklı CRUD, kamuya açık API, önbellek önemli
- Zorluk: istemci farklı alanlar istediğinde fazla veya eksik veri (over/under-fetching)
GraphQL
İstemcinin tam olarak ihtiyaç duyduğu alanları tek sorguda istediği stildir. Mobil uygulamalar ve zengin arayüzler için ağ trafiğini azaltır.
- Uygun: çok sayıda ilişkili varlık, farklı istemcilerin farklı ihtiyacı
- Zorluk: önbellek ve oran sınırlama daha karmaşık, sorgu maliyeti yönetilmeli
RPC tarzı
Uzaktaki bir fonksiyonu çağırma modelidir. Servisler arası iç iletişimde, düşük gecikme ve sıkı sözleşme gerektiğinde tercih edilir.
Webhook (olay bildirimi)
Bir olay gerçekleştiğinde (ödeme alındı, kargo çıktı, form dolduruldu) sağlayıcı sizin belirttiğiniz adrese istek gönderir. Sürekli sorgulama yerine olay geldiğinde işleme yapılır.
İmza doğrulaması, tekrar denemeler ve aynı olayın iki kez gelmesine karşı fikir birliği (idempotency) şarttır.
Gerçek zamanlı bağlantı
Anlık bildirim, canlı gösterge veya sohbet gibi ihtiyaçlarda sürekli açık bağlantı (WebSocket veya sunucu gönderimli olaylar) kullanılır.
Her API için ortak disiplin
- Sürümleme: kırıcı değişiklik yeni sürümle gelir, eski sürüm makul süre yaşar
- Kimlik ve yetki: anahtar, jeton veya OAuth; her isteğin sahibi bilinir
- Oran sınırlama: kötüye kullanım ve maliyet kontrolü
- Tutarlı hata modeli: kod, mesaj ve izlenebilir kimlik
- Sözleşme dokümantasyonu: örnek istek ve yanıtlarla