Idempotency
Aynı mutasyon isteğini ağ kesintisi, timeout veya retry yüzünden iki kere göndermek istemediğinizde Idempotency-Key header'ı kullanın.
Nasıl çalışır?
POST/PATCH/DELETEisteğinize benzersiz bir key ekleyin (örn. UUID v4)- Sunucu key'i alır ve işler
- Başarılı (2xx) yanıtları 24 saat boyunca cache'ler
- Aynı key ile gelen sonraki istek → cached yanıt geri döner, downstream tekrar tetiklenmez
POST /v1/offers HTTP/1.1
Idempotency-Key: 6c1f7d27-3a85-4c1f-9ad2-22b14c6a4e7c
Content-Type: application/json
{ "variantId": "...", "price": 29.99, "quantity": 10 }Key formatı
| Kural | Değer |
|---|---|
| Maksimum uzunluk | 64 karakter |
| İzinli karakterler | a-z, A-Z, 0-9, -, _ |
| TTL | 24 saat |
| Scope | API key başına izole (farklı anahtarlar aynı key'i çakıştırmaz) |
Geçersiz key formatında:
{
"type": "https://public-api.epinpark.com/problems/invalid-idempotency-key",
"title": "Invalid Idempotency-Key",
"status": 400,
"detail": "Idempotency-Key must be at most 64 characters and contain only letters, digits, hyphens, and underscores."
}Ne zaman kullanılır?
Önerilen kullanım senaryoları
- Sipariş tamamlama (fulfillment) — ağ timeout sonrası retry
- Fatura oluşturma — duplicate invoice oluşmasın
- Stok kodu yükleme — aynı kod batch'i iki kez yüklenmesin
- İade resolution — aynı çözüm iki kez girilmesin
Body değişirse
Aynı Idempotency-Key ile farklı body göndermek hata değildir, ama ilk yanıt
geri döner — yeni body işlenmez. Bu nedenle her anlamca farklı istek için
yeni key üretin.
Ne zaman cache'lenmez?
- 4xx / 5xx yanıtlar cache'lenmez — başarısız isteği tekrar göndererek farklı sonuç alabilirsiniz
- Header eksikse normal işlenir, idempotency uygulanmaz
GET/HEADistekleri için bu header anlamsızdır (zaten idempotent)
Örnek: güvenli retry mantığı
Key'i persist edin
Retry'ı farklı bir process veya uygulama restart'ı sonrasına yayıyorsanız,
Idempotency-Key'i veritabanı veya kuyrukta saklayın. Her retry'da yeni UUID
üretirseniz idempotency garantisi kalmaz.