Bir API, web sitesinden farklı bir iş yüküdür. Ziyaretçiler değil programlar tarafından çağrılır; bu da trafiğin daha düzenli ama daha yoğun, hataların daha az affedilir ve kesintilerin daha görünür olması demektir.
Bu rehber, kendi sanal sunucunuz üzerinde bir API servisini üretime hazır biçimde çalıştırmayı anlatıyor.
API'yi Web Sitesinden Ayıran Beş Şey
- Önbellek çoğu zaman kullanılamaz. Yanıtlar isteğe özgüdür; sayfa önbelleğinin sunduğu kurtarıcı etki burada yoktur.
- İstemciler tekrar dener. Bir hata döndüğünde tarayıcı gibi vazgeçmezler; genellikle otomatik olarak tekrar denerler ve bu, sorunlu bir anı istek seline çevirebilir.
- Trafik düzenlidir ama yoğundur. Zamanlanmış entegrasyonlar aynı dakikada toplu istek üretir.
- Hatalar sessiz kalabilir. Kimse "sayfa açılmıyor" demez; bir entegrasyon günlerce başarısız çalışabilir.
- Sürüm uyumluluğu zorunludur. Bir web sayfasını değiştirmek serbesttir; API yanıt yapısını değiştirmek, ona bağlı tüm istemcileri kırar.
Hız Sınırlama: Pazarlıksız
Hız sınırlaması olmayan bir API, tek bir hatalı istemcinin tüm servisi durdurabileceği bir servistir. Sonsuz döngüye girmiş bir entegrasyon, saniyede yüzlerce istek üretebilir — kötü niyet gerekmez, bir yazılım hatası yeter.
Sınırlamayı iki katmanda kurun:
- Ters vekil katmanında. Kaba bir üst sınır: IP başına belirli bir sürede kabul edilecek istek sayısı. Bu katman, uygulamanız hiç çalışmadan isteği reddeder — en ucuz savunmadır.
- Uygulama katmanında. İnce ayar: API anahtarı başına kota, uç nokta bazında farklı sınırlar. Pahalı uç noktalara (arama, rapor) daha sıkı sınır uygulayın.
Sınırı İstemciye Bildirin
İyi bir API, istemciye kalan kotasını ve sınırın ne zaman sıfırlanacağını yanıt başlıklarında bildirir. Sınıra takıldığında ise ne zaman tekrar deneyebileceğini söyler.
Bu bilgilendirme olmadan istemciler körlemesine tekrar dener ve durumu kötüleştirir. Bilgilendirildiklerinde ise bekleyip düzgün davranırlar.
Kimlik Doğrulama
| Yöntem | Uygun olduğu yer | Dikkat |
|---|---|---|
| API anahtarı | Sunucudan sunucuya entegrasyon | Tarayıcı tarafında kullanılamaz |
| Kısa ömürlü jeton | Kullanıcı oturumları | Yenileme akışı gerekir |
| Yetkilendirme protokolü | Üçüncü taraf erişimi | Kurulumu karmaşık |
| Karşılıklı sertifika | Yüksek güvenlikli entegrasyon | Sertifika yönetimi yükü |
Hangi yöntemi seçerseniz seçin üç kural geçerlidir: kimlik bilgileri yalnızca HTTPS üzerinden taşınmalı, URL sorgu parametresinde asla gönderilmemeli (loglara düşer) ve iptal edilebilir olmalıdır — sızan bir anahtarı iptal edemiyorsanız tek çareniz tüm istemcileri güncellemektir.
Kararlılık: Zincirleme Çökmeyi Önlemek
API'ler genellikle başka servislere bağımlıdır: veritabanı, dış API'ler, ödeme sağlayıcıları. Bu bağımlılıklardan biri yavaşladığında, sizin API'niz de yavaşlar ve istekler birikir.
Üç önlem bu zinciri kırar:
- Zaman aşımı tanımlayın. Dış bir servise yapılan çağrının süresiz beklemesine izin vermeyin. Zaman aşımı olmayan tek bir çağrı, tüm işçileri kilitleyebilir.
- Devre kesici kullanın. Bir bağımlılık sürekli hata veriyorsa, ona çağrı yapmayı geçici olarak durdurun ve hızlıca hata dönün. Böylece her istek o servisi beklemek yerine anında yanıtlanır.
- Zarif bozulma tasarlayın. İkincil bir bağımlılık çalışmıyorsa tüm isteği reddetmek yerine kısmi yanıt dönün. Öneri servisi çalışmıyor diye ürün detayı da dönmemesi gereksiz bir katılıktır.
Sürümleme
API'nizi kullanan istemciler sizin kontrolünüzde değildir. Yanıt yapısını değiştirmek, onları haber vermeden kırmak demektir.
Kural şudur: yeni alan eklemek güvenlidir, mevcut alanı kaldırmak veya anlamını değiştirmek değildir. İyi yazılmış bir istemci, tanımadığı alanları yok sayar; ama beklediği bir alan kaybolursa hata verir.
Kırıcı bir değişiklik gerekiyorsa yeni bir sürüm yayımlayın, eskisini bir süre çalışır tutun ve istemcilere geçiş için zaman tanıyın. Eski sürümü kapatmadan önce erişim loglarına bakıp hâlâ kullanılıp kullanılmadığını doğrulayın.
İzleme: Sessiz Hataları Yakalamak
API'lerde en tehlikeli durum, sessiz başarısızlıktır: bir entegrasyon günlerce hata alıyor olabilir ve kimse bildirmez.
İzlenmesi gerekenler:
- Hata oranı. Toplam isteklerin yüzde kaçı hata dönüyor? Ani artış için uyarı kurun.
- Yanıt süresi dağılımı. Ortalamaya değil, en yavaş isteklere bakın. Ortalama iyi görünürken isteklerin bir kısmı çok yavaş olabilir.
- Uç nokta bazında kırılım. Hangi uç nokta yavaş, hangisi hata üretiyor?
- İstemci bazında kırılım. Belirli bir entegrasyon mu sorun yaşıyor, yoksa sorun genel mi?
- Hız sınırına takılma sayısı. Artıyorsa ya bir istemci hatalı çalışıyor ya sınırlarınız gerçek kullanım için fazla dar.
Sonuç
API barındırmada web sitesinden en büyük fark, istemcilerin insan değil program olmasıdır: hata aldıklarında vazgeçmez, tekrar denerler. Bu yüzden hız sınırlama isteğe bağlı bir özellik değil, temel bir savunmadır. Bağımlılıklara zaman aşımı tanımlamak ise zincirleme çökmeleri önleyen ikinci kritik adımdır. Kaynakların size ayrıldığı bir VDS üzerinde bu katmanların hepsini kurabilirsiniz — ve bir API için hepsi gereklidir.
Sıkça Sorulan Sorular (SSS)
Hız sınırını nasıl belirlemeliyim?
Meşru istemcilerinizin gerçek kullanım desenini ölçüp üzerine pay ekleyin. Çok dar bir sınır normal kullanımı engeller; çok geniş bir sınır ise korumayı anlamsız kılar. Sınıra takılma sayısını izleyip zamanla ayarlayın.
API anahtarını nerede saklamalı?
Sunucu tarafında, sürüm kontrolünün dışında bir yapılandırma dosyasında. Tarayıcı tarafındaki koda gömülen bir anahtar herkese açıktır. URL sorgu parametresinde göndermeyin — sunucu loglarına düz metin olarak düşer.
API sürümlemesi şart mı?
Kullanıcılarınız sizin kontrolünüzde değilse evet. Yeni alan eklemek güvenlidir; mevcut alanı kaldırmak veya anlamını değiştirmek istemcileri kırar. Kırıcı değişiklikler için yeni sürüm yayımlayıp eskisini bir süre çalışır tutun.
API yanıtları önbelleğe alınabilir mi?
Kullanıcıya özel olmayan ve sık değişmeyen yanıtlar alınabilir — kategori listeleri, sabit veri setleri gibi. Kullanıcıya özgü yanıtları önbelleğe almak, bir kullanıcının başkasının verisini görmesine yol açar; bu, API tarafında yapılabilecek en ciddi hatalardan biridir.
