Kısaca
Token bucket veya kayan pencere algoritmalarını kullanarak API oran sınırlaması uygulayın. Standart IETF oran sınırlama başlıklarını (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset) ve sınırlar aşıldığında 429 Too Many Requests yanıtını döndürün. Modern PetstoreAPI, kullanıcı başına kotalar ve net hata yanıtları ile oran sınırlaması uygulamaktadır.
Giriş
Bir istemci, bir dakika içinde API'nize 10.000 istek gönderir. Veritabanınız çöker. İzleme uyarılarınız tetiklenir. Diğer müşterileriniz API'ye erişemez. Bir saldırı altındasınızdır veya belki de yeniden deneme döngüsünde hatalı bir istemciyle uğraşıyorsunuzdur.
Oran sınırlaması bunu önler. Bir istemcinin belirli bir zaman diliminde yapabileceği istek sayısını sınırlar. Limiti aştıklarında 429 Too Many Requests (Çok Fazla İstek) yanıtını döndürürsünüz. İstemci geri çekilir ve API'niz sağlıklı kalır.
Eski Swagger Petstore, oran sınırlamasını hiç uygulamıyor. Modern PetstoreAPI, standart IETF başlıkları, kullanıcı başına kotalar ve net hata yanıtları ile oran sınırlaması uyguluyor.
Bu rehberde, oran sınırlama algoritmalarını, standart başlıkları ve Modern PetstoreAPI'nin oran sınırlamasını nasıl doğru bir şekilde uyguladığını öğreneceksiniz.
API'lerin Neden Oran Sınırlamasına İhtiyacı Var?
Oran sınırlaması, API'nizi kötüye kullanıma karşı korur ve adil kullanımı sağlar.
Kötüye Kullanıma Karşı Koruma
1. Hizmet Reddi (DoS) saldırıları
Bir saldırgan, API'nizi kullanılamaz hale getirmek için isteklerle boğar. Oran sınırlaması, onların etkisini sınırlar.
2. Kimlik bilgisi doldurma (Credential stuffing)
Saldırganlar binlerce kullanıcı adı/şifre kombinasyonunu dener. Oran sınırlaması, onları yavaşlatır.
3. Veri kazıma (Data scraping)
Botlar tüm veri kümenizi kazır. Oran sınırlaması, kazımayı pratik olmaktan çıkarır.
4. Maliyet kontrolü
API'niz pahalı hizmetleri (AI modelleri, üçüncü taraf API'ler) çağırıyorsa, oran sınırlaması kontrol dışı maliyetleri önler.
Adil Kullanım
1. Bir istemcinin kaynakları tekeline almasını önleyin
Oran sınırlaması olmadan, saniyede 1000 istek yapan bir istemci diğer istemcileri kaynaklardan mahrum bırakabilir.
2. Öngörülebilir performans
Oran sınırlaması, tüm istemciler için tutarlı yanıt süreleri sağlar.
3. Katmanlı erişim
Ücretsiz katman: saatte 100 istek. Ücretli katman: saatte 10.000 istek. Oran sınırlaması bu katmanları uygular.
Operasyonel Faydalar
1. Kapasite planlaması
API'nizin kaldırabileceği maksimum yükü bilirsiniz.
2. Maliyet öngörülebilirliği
Oran sınırlamaları altyapı maliyetlerini sınırlar.
3. Zarif düşüş (Graceful degradation)
Yük altında, oran sınırlaması ardışık arızaları önler.
Oran Sınırlama Algoritmaları
Farklı algoritmaların farklı avantaj ve dezavantajları vardır.
1. Sabit Pencere
Sabit zaman pencerelerindeki istekleri sayar.
Nasıl çalışır:
Pencere 1 (00:00-00:59): 100 isteğe izin verilir
Pencere 2 (01:00-01:59): 100 isteğe izin verilir
Uygulama:
def is_allowed(user_id):
current_minute = get_current_minute()
key = f"rate_limit:{user_id}:{current_minute}"
count = redis.incr(key)
redis.expire(key, 60)
return count <= 100
Avantajları:
- Uygulaması basit
- Düşük bellek kullanımı
Dezavantajları:
- Ani yük problemi: İstemci 00:59'da 100, 01:00'da 100 istek yapabilir (2 saniyede 200)
2. Kayan Pencere
Kaydırılan bir zaman penceresindeki istekleri sayar.
Nasıl çalışır:
01:30'da, 00:30'dan 01:30'a kadar olan istekleri sayar (son 60 dakika).
Uygulama:
def is_allowed(user_id):
now = time.time()
window_start = now - 3600 # 1 saat önce
key = f"rate_limit:{user_id}"
# Eski istekleri kaldır
redis.zremrangebyscore(key, 0, window_start)
# Penceredeki istekleri say
count = redis.zcard(key)
if count < 100:
redis.zadd(key, {now: now})
redis.expire(key, 3600)
return True
return False
Avantajları:
- Ani yük problemi yok
- Doğru oran sınırlaması
Dezavantajları:
- Daha yüksek bellek kullanımı (her istek için zaman damgası saklar)
- Daha karmaşık
3. Token Kovası (Token Bucket)
Belirli bir hızda kovaya jetonlar eklenir. Her istek bir jeton tüketir.
Nasıl çalışır:
Kova kapasitesi: 100 jeton
Yeniden doldurma hızı: saniyede 10 jeton
İstek: 1 jeton tüketir
Uygulama:
def is_allowed(user_id):
now = time.time()
key = f"rate_limit:{user_id}"
# Mevcut durumu al
data = redis.hgetall(key)
tokens = float(data.get('tokens', 100))
last_refill = float(data.get('last_refill', now))
# Jetonları doldur
elapsed = now - last_refill
tokens = min(100, tokens + elapsed * 10) # 10 jeton/sn
if tokens >= 1:
tokens -= 1
redis.hset(key, 'tokens', tokens)
redis.hset(key, 'last_refill', now)
redis.expire(key, 3600)
return True
return False
Avantajları:
- Ani yüklemelere izin verir (kova kapasitesine kadar)
- Düzgün oran sınırlaması
- Endüstri standardı
Dezavantajları:
- Sabit pencereden daha karmaşık
- Durumun saklanmasını gerektirir
4. Sızdıran Kova (Leaky Bucket)
İstekler bir kuyruğa eklenir ve sabit bir hızda işlenir.
Nasıl çalışır:
Kuyruk kapasitesi: 100 istek
İşleme hızı: saniyede 10 istek
Avantajları:
- Düzgün çıkış hızı
- Aşağı akış hizmetlerini korumak için iyi
Dezavantajları:
- Gecikme ekler (istekler kuyrukta bekler)
- Uygulaması karmaşık
Hangi Algoritma Kullanılmalı?
Çoğu API için: Token Kovası
Endüstri standardıdır, makul ani yüklere izin verir ve düzgün oran sınırlaması sağlar.
Modern PetstoreAPI, kullanıcı başına kotalarla token bucket kullanır.
Standart Oran Sınırlama Başlıkları
IETF standart başlıklarını kullanın (draft-ietf-httpapi-ratelimit-headers).
Standart Başlıklar
RateLimit-Limit: Zaman penceresinde izin verilen maksimum istek sayısı
RateLimit-Limit: 100
RateLimit-Remaining: Mevcut pencerede kalan istek sayısı
RateLimit-Remaining: 45
RateLimit-Reset: Oran sınırlamasının sıfırlanmasına kadar geçen saniye sayısı
RateLimit-Reset: 3600
Örnek Yanıt
GET /pets
200 OK
RateLimit-Limit: 100
RateLimit-Remaining: 99
RateLimit-Reset: 3600
{
"data": [...]
}
Eski Başlıklar (Kullanımdan Kaldırıldı)
Birçok API standart olmayan başlıklar kullanır:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1710331200
Bunları kullanmayın. X- öneki kullanımdan kaldırılmıştır ve formatı standartlaştırılmamıştır.
Modern PetstoreAPI Oran Sınırlamasını Nasıl Uygular?
Modern PetstoreAPI, standart başlıklarla token bucket oran sınırlamasını uygular.
Kademelere Göre Oran Sınırlamaları
Ücretsiz kademe:
- Saatte 100 istek
- Günde 1.000 istek
Pro kademe:
- Saatte 10.000 istek
- Günde 100.000 istek
Kurumsal kademe:
- Özel sınırlar
Uygulama
Başarılı istek:
GET /v1/pets
200 OK
RateLimit-Limit: 100
RateLimit-Remaining: 99
RateLimit-Reset: 3540
{
"data": [...]
}
Oran sınırı aşıldığında:
GET /v1/pets
429 Too Many Requests
Content-Type: application/problem+json
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 120
Retry-After: 120
{
"type": "https://petstoreapi.com/errors/rate-limit-exceeded",
"title": "Oran Sınırı Aşıldı",
"status": 429,
"detail": "Saatte 100 istek olan oran sınırını aştınız",
"instance": "/v1/pets",
"retryAfter": 120,
"limit": 100,
"window": "1s"
}
Kullanıcı Başına vs. IP Başına
Kullanıcı başına (kimliği doğrulanmış istekler):
Kullanıcı kimliği veya API anahtarına göre oran sınırlaması. Daha doğru ve adil.
user_id = get_authenticated_user()
is_allowed(user_id)
IP başına (kimliği doğrulanmamış istekler):
IP adresine göre oran sınırlaması. Daha az doğru (paylaşılan IP'ler, VPN'ler) ancak hiçbir şeyden iyidir.
ip_address = request.remote_addr
is_allowed(ip_address)
Modern PetstoreAPI, kimliği doğrulanmış istekler için kullanıcı başına oran sınırlaması ve genel uç noktalar için IP başına oran sınırlaması kullanır.
Oran Sınırlaması Yanıt Formatı
Oran sınırları aşıldığında, 429 yanıtını RFC 9457 hata formatıyla döndürün.
Yanıt Yapısı
{
"type": "https://petstoreapi.com/errors/rate-limit-exceeded",
"title": "Oran Sınırı Aşıldı",
"status": 429,
"detail": "Oran sınırınızı aştınız. Lütfen daha sonra tekrar deneyin.",
"instance": "/v1/pets",
"retryAfter": 120,
"limit": 100,
"remaining": 0,
"reset": 120,
"window": "1s"
}
Başlıklar
429 Çok Fazla İstek
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 120
Retry-After: 120
Retry-After: İstemcilere ne zaman yeniden deneme yapabileceklerini söyler (saniye cinsinden).
Apidog ile Oran Sınırlarını Test Etme
Apidog, oran sınırlama davranışını test etmenize yardımcı olur.
Test Senaryoları
1. Normal kullanım:
50 istek gönder → Hepsi başarılı
RateLimit-Remaining'in azaldığını kontrol edin
2. Limiti aşma:
101 istek gönder → 101. istek 429 döndürür
Hata yanıt formatını doğrulayın
Retry-After başlığını kontrol edin
3. Sıfırlama davranışı:
Limiti aş → Sıfırlamayı bekle → Limitin geri yüklendiğini doğrula
4. Farklı kademeler:
Ücretsiz kademeyi test et (saatte 100)
Profesyonel kademeyi test et (saatte 10.000)
Sınırların doğru uygulandığını doğrula
Apidog Test Örneği
// Oran sınırlama başlıklarını test et
pm.test("Oran sınırlama başlıkları mevcut", () => {
pm.response.to.have.header("RateLimit-Limit");
pm.response.to.have.header("RateLimit-Remaining");
pm.response.to.have.header("RateLimit-Reset");
});
// Oran sınırı aşıldığında test et
pm.test("Limit aşıldığında 429 döndürür", () => {
// 101 istek yap
for (let i = 0; i < 101; i++) {
pm.sendRequest("GET /v1/pets");
}
pm.response.to.have.status(429);
});
Oran Sınırlama En İyi Uygulamaları
1. Standart başlıkları kullanın
Özel X- başlıkları yerine IETF standart başlıklarını kullanın.
2. 403 yerine 429 döndürün
429 "çok fazla istek" anlamına gelir. 403 "yasaklandı" anlamına gelir. Bunları karıştırmayın.
3. Retry-After'ı dahil edin
İstemcilere ne zaman yeniden deneyebileceklerini söyleyin.
4. Limitlerinizi belgeleyin
Oran limitlerini belgelerde görünür hale getirin.
5. Farklı kademeler sağlayın
Ücretsiz kademe: düşük limitler. Ücretli kademe: daha yüksek limitler.
6. IP yerine kullanıcıya göre oran sınırlaması yapın
Kullanıcı başına limitler daha doğru ve adildir.
7. Ani yüklere izin verin
Token bucket, normal kullanımı cezalandırmadan makul ani yüklere izin verir.
8. Oran sınırlaması isabetlerini izleyin
İstemcilerin oran limitlerine ne sıklıkta ulaştığını takip edin. Yüksek oranlar sorunları gösterir.
9. Oran sınırlaması durum uç noktası sağlayın
GET /v1/rate-limit
200 OK
{
"limit": 100,
"remaining": 45,
"reset": 3540
}
10. Oran sınırlamasını test edin
Dağıtımdan önce oran sınırlama davranışını test etmek için Apidog kullanın.
Sonuç
Oran sınırlaması, API'nizi kötüye kullanımdan korur ve adil kullanım sağlar. Standart IETF başlıkları (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset) ile token bucket algoritmasını kullanın. Sınırlar aşıldığında RFC 9457 hata formatıyla 429 Too Many Requests (Çok Fazla İstek) yanıtını döndürün.
Modern PetstoreAPI, kullanıcı başına kotalar, standart başlıklar ve net hata yanıtları ile oran sınırlamasını doğru bir şekilde uygulamaktadır. Uygulama ayrıntıları için belgeleri kontrol edin.
Oran sınırlamanızın yük altında doğru çalıştığından ve uç durumları düzgün bir şekilde ele aldığından emin olmak için Apidog ile test edin.
Sıkça Sorulan Sorular
Hangi oran limitlerini belirlemeliyim?
Muhafazakar başlayın: ücretsiz kademe için saatte 100 istek, ücretli kademe için saatte 10.000 istek. Kullanım modellerine ve altyapı kapasitesine göre ayarlayın.
IP'ye mi yoksa kullanıcıya mı göre oran sınırlaması yapmalıyım?
Kimliği doğrulanmış istekler için kullanıcıya (API anahtarı) göre oran sınırlaması yapın. IP tabanlı oran sınırlamasını yalnızca genel uç noktalar için kullanın.
Bir istemci oran sınırını aşarsa ne olur?
Retry-After başlığı ile 429 Too Many Requests (Çok Fazla İstek) yanıtını döndürün. İstemciyi kalıcı olarak engellemeyin; pencere sıfırlandıktan sonra yeniden denemelerine izin verin.
Webhook'lar için oran limitlerini nasıl yönetirim?
Webhook'lar sunucudan sunucuya olduğundan, oran limitleri daha yüksek olmalıdır. Webhook'lar ve API çağrıları için ayrı limitler düşünün.
Dahili hizmetleri oran sınırlamasına tabi tutmalı mıyım?
Evet, ancak çok daha yüksek limitlerle. Oran sınırlaması, dahili sistemlerde bile ardışık arızaları önler.
Oran sınırlamasını nasıl test ederim?
Birden çok istek göndermek ve 429 yanıtlarını, oran sınırlama başlıklarını ve sıfırlama davranışını doğrulamak için Apidog kullanın.
API'm bir CDN'nin arkasındaysa ne olur?
CDN önbelleğe alma yükü azaltır, ancak önbellek isabetleri ve POST/PUT/DELETE istekleri için yine de oran sınırlamasına ihtiyacınız vardır.
Birden çok sunucuda oran sınırlamasını nasıl uygularım?
Tüm sunucularda oran limitlerini izlemek için paylaşılan bir veri deposu (Redis, Memcached) kullanın. Yerel bellek kullanmayın; dağıtılmış sistemlerde çalışmaz.