API Performansı: Hız Sınırlama, Sayfalandırma ve Eşzamansız İşleme

API'niz en yüksek yük altında yalnızca en yavaş uç noktası kadar hızlıdır. Veritabanı bağlantılarını 5 saniye boyunca tutan, optimize edilmemiş tek bir uç nokta, bağlantı havuzunuzu tüketebilir ve platformunuzun tamamında arızaları basamaklandırabilir. API performans mühendisliği üç temele odaklanır: API'nizi aşırı yükten korumak (hız sınırlama), büyük veri kümelerini verimli bir şekilde işlemek (sayfalandırma) ve pahalı işlemleri istek döngüsünün dışına taşımak (eşzamansız işleme).

Önemli Çıkarımlar

• Token kovası ve kayan pencere, kullanım durumlarının %95'ini kapsayan iki hız sınırlayıcı algoritmadır; ani tolerans veya sıkı uygulama isteyip istemediğinize göre seçim yapın
• İmleç tabanlı sayfalandırma, atlanan satırların sayılmasını önlediği için büyük veri kümeleri için ofset sayfalandırmaya göre daha iyi performans gösterir
• İş kuyruklarıyla eşzamansız işleme, e-posta göndermeyi, PDF oluşturmayı ve web kancası dağıtımını istek yolunun dışına taşıyarak P95 yanıt sürelerini azaltır
• Brotli ile yanıt sıkıştırma, yük boyutlarını %70-85 oranında azaltarak doğrudan istemci tarafı işlemenin daha hızlı olmasını sağlar

---

Hız Sınırlama Algoritmaları

Hız sınırlama, API'nizi kötüye kullanıma karşı korur, adil kaynak tahsisi sağlar ve trafik artışları sırasında kademeli arızaları önler. Seçtiğiniz algoritma, patlamaların nasıl ele alınacağını ve sınırlayıcı davranışın tüketiciler açısından ne kadar öngörülebilir olduğunu belirler.

Jeton Kovası

Token kovası algoritması çoğu API için en pratik seçimdir. Bir kova, jetonları maksimum kapasiteye kadar tutar. Jetonlar sabit bir oranda (yeniden doldurma oranı) eklenir. Her istek bir jeton tüketir. Paket boşsa istek reddedilir veya sıraya alınır.

Jeton kovasının en önemli avantajı patlama toleransıdır. Bir müşteri bir süredir istekte bulunmadıysa, kovası doludur ve kova kapasitesine kadar istek patlaması yapabilir. Bu, doğal kullanım kalıplarıyla eşleşir; bir kontrol panelini yükleyen bir istemci, hızlı bir şekilde art arda 20 istekte bulunabilir, ardından 30 saniye boyunca hiçbir şey yapmayabilir.

Bir e-Ticaret API'si için yapılandırma örneği:

• Kova boyutu: 100 jeton
• Doldurma hızı: saniyede 10 jeton
• Bu, uzun vadede saniyede 10 isteği sürdürürken 100'e kadar istek artışına izin verir

Sürgülü Pencere Sayacı

Kayar pencere sayacı, kayan pencere günlüğünün hassasiyetini sabit pencerenin bellek verimliliğiyle birleştirir. Geçerli ve önceki pencereye ilişkin sayaçları tutar, ardından isteğin geçerli pencerenin ne kadar içine düştüğüne bağlı olarak ağırlıklı bir sayım hesaplar.

45 saniyede değerlendirilen 60 saniyelik bir pencere için etkili sayım şöyledir: (önceki pencere sayısı * 0,25) + (geçerli pencere sayısı). Bu, bireysel istek zaman damgalarını saklamadan sabit pencerelerin sınır patlaması sorununu ortadan kaldırır.

Redis ile Uygulama

Redis, TTL ile atomik artış işlemleri sağladığı için dağıtılmış hız sınırlaması için standart yedekleme deposudur. Sabit pencereler için EXPIRE ile INCR'yi veya kayan pencereler için ZADD ve ZRANGEBYSCORE ile sıralanmış kümeleri kullanın. Belirteç kümesi için Redis Lua komut dosyaları atomik kontrol ve azaltma işlemleri sağlar.

Hız sınırlama başlıkları sınırları API tüketicilerine iletir:

• X-RateLimit-Limit -- pencerede izin verilen maksimum istekler
• X-RateLimit-Remaining -- geçerli pencerede kalan istekler
• X-RateLimit-Reset -- Pencere sıfırlandığında Unix zaman damgası
• Retry-After -- istemcinin yeniden denemesine saniyeler kaldı (429 yanıtta)

---

Sayfalandırma Stratejileri

Her liste uç noktası sayfalara ayrılmalıdır. Sınırsız sonuç kümelerinin döndürülmesi bant genişliğini boşa harcar, veritabanını zorlar ve veriler büyüdükçe zaman aşımı hataları riskiyle karşı karşıya kalır.

Ofset Sayfalandırma

Ofset sayfalandırma, LIMIT ve OFFSET SQL cümlelerini kullanır. İstemci ?page=3&limit=20 isteğinde bulunur ve sunucu OFFSET 40 LIMIT 20'e çevirir.

Avantajları:

• Uygulaması ve anlaşılması basit
• Müşteriler herhangi bir sayfaya doğrudan atlayabilir
• Toplam sayım "Sayfa X / Y" kullanıcı arayüzünü etkinleştirir

Dezavantajları:

• Performans, yüksek ofsetlerle düşüyor -- OFFSET 1000000, sonuçları döndürmeden önce hâlâ 1.000.000 satırı tarıyor
• Sayfalar arasında veri değiştiğinde tutarsız sonuçlar (yeni veri eklenirken veya silinirken satırlar kayar)
• Toplam sayı sorgusu (COUNT(*)) büyük tablolarda pahalı olabilir

İmleç Tabanlı Sayfalandırma

İmleç tabanlı sayfalandırma, sonuç kümesindeki konumu işaretlemek için opak bir imleç (tipik olarak kodlanmış bir birincil anahtar veya zaman damgası) kullanır. İstemci ?cursor=abc123&limit=20 isteğinde bulunur ve sunucu imleci WHERE yan tümcesi olarak kullanır: WHERE id > decoded(abc123) LIMIT 20.

Avantajları:

• Veri kümesindeki konumdan bağımsız olarak tutarlı performans - ofset taraması yok
• Sayfalar arasında veri değiştiğinde bile istikrarlı sonuçlar
• Sonsuz kaydırma ve gerçek zamanlı yayınlar için doğal uyum

Dezavantajları:

• Rastgele sayfalara atlanamıyor ("50. sayfaya git" yok)
• Özellikle çok sütunlu sıralama düzenlerinde uygulanması daha karmaşık
• Gerekiyorsa toplam sayı ayrı olarak sağlanmalıdır

Hangi Sayfalandırmanın Kullanılacağı

Sayfalandırma Yanıt Formatı

İyi tasarlanmış bir sayfalandırma yanıtı, müşterilerin gezinmesi gereken meta verileri içerir:

{
  "data": [],
  "pagination": {
    "total": 15432,
    "limit": 20,
    "hasMore": true,
    "nextCursor": "eyJpZCI6MTAwfQ=="
  }
}

---

İş Kuyruklarıyla Eşzamansız İşleme

Eşzamanlı API uç noktaları 200 ms içinde yanıt döndürmelidir. Daha uzun süren tüm işlemler (e-posta göndermek, PDF oluşturmak, görüntüleri işlemek, harici API'leri çağırmak, raporları çalıştırmak) arka plandaki iş kuyruğuna taşınmalıdır.

İş Kuyruğu Modeli

1. API uç noktası isteği doğrular ve bir iş kaydı oluşturur
2. İş sıraya alınır (Redis, RabbitMQ, SQS)
3. API, 202 Kabul edildi yanıtı ve iş kimliğiyle hemen geri döner
4. Bir çalışan süreci işi alır ve eşzamansız olarak yürütür
5. İstemci iş durumu için yoklama yapar veya tamamlandığında bir webhook geri araması alır

Yaygın Eşzamansız Kullanım Durumları

E-posta gönderme -- SMTP işlemleri sağlayıcıya bağlı olarak 500 ms-3s sürer. E-postaların sıraya alınması, API yanıt süresini azaltır ve kullanıcıyı engellemeden geçici hatalar için yeniden deneme mantığına olanak tanır.

PDF oluşturma -- Fatura, rapor oluşturmak veya dosyaları dışa aktarmak yoğun CPU ve bellek tüketimi gerektirir. Bunları özel çalışanlarda çalıştırmak, API istek işlemede kaynak çekişmesini önler.

Web kancası dağıtımı -- Giden web kancaları, üçüncü taraf sunucunun kullanılabilirliğine bağlıdır. Sisteminizi engellemeden geçici arızaları gidermek için üstel geri çekilme yeniden denemesiyle (1 saniye, 2 saniye, 4 saniye, 8 saniye, 5 dakikaya kadar) web kancası dağıtımlarını sıraya koyun.

Verileri içe ve dışa aktarma -- 100.000 satırlık CSV yüklemelerinin işlenmesi hiçbir zaman bir istek döngüsünde gerçekleşmemelidir. Yüklemeyi kabul edin, iş kimliğini döndürün ve satırları toplu olarak işleyin.

Sıra Seçimi

---

Yanıt Optimizasyonu

Uygulama mantığının ötesinde, yanıtın kendisi boyut ve teslimat hızı açısından optimize edilebilir.

Sıkıştırma

Ağ üzerindeki yük boyutlarını azaltmak için yanıt sıkıştırmayı etkinleştirin. Modern sıkıştırma algoritmaları, metin tabanlı yükleri (JSON, HTML, CSS, JavaScript) önemli ölçüde azaltır.

Statik varlıklar için Brotli'yi (derleme sırasında önceden sıkıştırılmış) ve dinamik yanıtlar için geri dönüş olarak gzip'i kullanın. NestJS'de sıkıştırma ara yazılımı bunu otomatik olarak gerçekleştirir, ancak üretimde Nginx'in CPU'yu uygulama sunucunuzdan boşaltmak için sıkıştırmayı işlemesine izin verin.

Alan Seçimi

API tüketicilerinin yalnızca ihtiyaç duydukları alanları talep etmelerine izin verin. GraphQL bunu doğası gereği yapar, ancak REST API'leri alan seçimini ?fields=id,name,price sorgu parametresiyle destekleyebilir. Bu, yük boyutunu azaltır ve yalnızca gerekli sütunları seçerek veritabanı sorgularını optimize edebilir.

Yanıt Önbelleğe Alma Başlıkları

API yanıtlarında uygun Önbellek Denetimi başlıklarını ayarlayın. Genel liste uç noktaları (ürünler, kategoriler) 5 dakika boyunca önbelleğe almak için Cache-Control: public, max-age=300 kullanabilir. Kimliği doğrulanmış uç noktalar, yeniden doğrulamayla tarayıcının önbelleğe alınmasına izin verirken CDN'nin önbelleğe alınmasını önlemek için Cache-Control: private, no-cache kullanmalıdır.

Önbelleğe alma stratejileri hakkında daha fazla bilgi için Redis, CDN ve HTTP önbelleğe alma hakkındaki ayrıntılı kılavuzumuza bakın.

---

Bağlantı Yönetimi

Veritabanı ve HTTP bağlantıları, yük altında dikkatli bir şekilde yönetilmesi gereken sınırlı kaynaklardır.

Veritabanı Bağlantı Havuzu Oluşturma

Bağlantı havuzu, bir dizi yeniden kullanılabilir veritabanı bağlantısını korur. Havuzlama olmadan, her API isteği yeni bir veritabanı bağlantısı açar (50-100 ms ek yük) ve yanıttan sonra onu kapatır. Havuzlamada, istekler havuzdan bağlantıları ödünç alır ve bittiğinde bunları geri verir.

Havuz boyutlandırma formülü: bağlantılar = (core_count * 2) + active_spindle_count. SSD depolamaya sahip 4 çekirdekli bir sunucu için uygulama örneği başına 10-20 bağlantı iyi bir başlangıç ​​noktasıdır. Havuz kullanımını izleyin; düzenli olarak %80'i aşarsa havuz boyutunu artırın veya sorgu süresini optimize edin.

HTTP Canlı Tutma

Yukarı akış hizmetlerine (veritabanları, Redis, harici API'ler) bağlantılar için HTTP'yi canlı tutmayı etkinleştirin. Bu, istek başına yeni bağlantılar oluşturmak yerine TCP bağlantılarını yeniden kullanır ve TCP anlaşması ve TLS anlaşması yükünü ortadan kaldırır (yeni bağlantı başına 50-200 ms).

---

Sıkça Sorulan Sorular

Genel bir API için hangi hız sınırlarını ayarlamalıyım?

Muhafazakar sınırlarla başlayın ve meşru kullanım kalıplarına göre ayarlayın. Ortak bir başlangıç ​​noktası, kimliği doğrulanmış kullanıcılar için dakikada 100 istek ve anonim kullanıcılar için dakikada 20 istektir. 429 yanıt oranlarını izleyin; meşru kullanıcılar sık ​​sık sınırlara ulaşırsa bunları artırın. Premium API katmanları için daha yüksek sınırlar sağlayın.

Veriler sayfalar arasında değiştiğinde sayfalandırmayı nasıl hallederim?

İmleç tabanlı sayfalandırma, sıralanan verilerde belirli bir konuma sabitlendiğinden bunu doğal olarak halleder. Ofset sayfalandırmayla, ortaya çıkan belge sayfalar arasında kayabilir. Kritik kullanım durumları için (finansal raporlar, veri aktarımları), sayfalandırmanın başlangıcında verilerin anlık görüntüsünü alın ve anlık görüntünün üzerinde sayfalandırma yapın.

Performans için REST mi yoksa GraphQL mi kullanmalıyım?

Alan seçimi ve uygun önbelleğe alma özelliğiyle REST, basit, iyi tanımlanmış uç noktalar için daha hızlıdır. GraphQL, karmaşık veri gereksinimleri için aşırı ve az getirmeyi ortadan kaldırır ancak sorgu ayrıştırma yükünü ekler ve HTTP önbelleğe almayı zorlaştırır. Önbelleğe alma ihtiyaçları olan genel API'ler için REST'i ve karmaşık ön uç veri gereksinimlerini karşılayan dahili API'ler için GraphQL'i kullanın.

Üretimdeki API performansını nasıl izlerim?

Uç nokta başına P50, P95 ve P99 yanıt sürelerini izleyin. SLO'nuzu ihlal eden P95 için uyarılar ayarlayın (genellikle 200-500 ms). Veritabanında, önbellekte, harici hizmetlerde ve uygulama mantığında harcanan sürenin dökümünü almak için dağıtılmış izlemeyi kullanın. Ayrıntılı kurulum için izleme ve gözlemlenebilirlik ile ilgili kılavuzumuza bakın.

---

Sırada Ne Var

API uç noktalarınızı eksik sayfalandırma, hız sınırlaması olmayan korumasız genel uç noktalar ve eşzamansız olması gereken eşzamanlı işlemler açısından denetleyerek başlayın. Bu üç değişiklik genellikle P95 yanıt sürelerini %50-70 oranında azaltır ve en yaygın üretim olaylarını önler.

Performans mühendisliği perspektifinin tamamı için iş platformunuzu ölçeklendirme hakkındaki temel kılavuzumuza bakın. API'nize güç veren veritabanı katmanı için sorgu optimizasyon kılavuzumuzu okuyun.

ECOSIRE, Odoo ERP ve özel mimariler üzerinde iş platformları için yüksek performanslı API'ler oluşturur. API performans incelemesi için bize ulaşın.

---

ECOSIRE tarafından yayınlandı — işletmelerin Odoo ERP, Shopify eCommerce ve OpenClaw AI genelinde yapay zeka destekli çözümlerle ölçeklenmesine yardımcı oluyor.