1. Giriş: Idempotency Nedir?

Idempotency (tek etkilik), bir işlemin kaç kez tekrarlanırsa tekrarlansın aynı sonucu üretmesi anlamına gelir. HTTP protokolünde GET, HEAD, PUT, DELETE ve OPTIONS metodları doğal olarak idempotent kabul edilirken, POST ve PATCH metodları değildir. Bu durum, özellikle ağ hatalarının yaşandığı senaryolarda ciddi sorunlara yol açabilir.

Bir ödeme isteği düşünün: Client POST isteği gönderir, sunucu işlemi tamamlar ancak yanıt network hatası nedeniyle client'a ulaşmaz. Client ne yapmalıdır? İsteği tekrar gönderirse müşteri iki kez ücretlendirilebilir. Göndermezse ödeme hiç gerçekleşmemiş olabilir. İşte Idempotency-Key tam bu sorunu çözmek için tasarlanmıştır.

2. IETF Standardı: draft-ietf-httpapi-idempotency-key-header

IETF (Internet Engineering Task Force), HTTP API'leri için standart bir idempotency mekanizması tanımlamak amacıyla bir draft RFC üzerinde çalışmaktadır. Bu standart, Stripe ve PayPal gibi şirketlerin yıllardır kullandığı pratiklerden ilham almaktadır.

2.1 Header Formatı

Idempotency-Key: "8e03978e-40d5-43e8-bc93-6894a57f9324"

Standart, key değerinin bir String olmasını ve RFC 8941 (Structured Field Values) formatına uymasını gerektirir. UUID v4 kullanımı önerilmektedir.

2.2 Temel Gereksinimler

• Uniqueness: Her idempotency key benzersiz olmalı ve farklı payload'larla yeniden kullanılmamalıdır.

• TTL (Time-To-Live): Sunucu, key'lerin ne kadar süre saklanacağını belirlemeli ve dokümante etmelidir.

• Fingerprinting: Aynı key ile farklı payload gönderildiğinde bu durumun tespit edilmesi için hash mekanizması kullanılmalıdır.

• Response Caching: İlk başarılı yanıt saklanmalı ve tekrar isteklerde bu yanıt dönülmelidir.

2.3 Standart Hata Kodları

HTTP Kodu	Durum	Açıklama
400	Bad Request	Idempotency-Key header eksik
409	Conflict	Aynı key ile istek hâlâ işleniyor
422	Unprocessable Content	Aynı key, farklı payload ile kullanılmış

3. Endüstri Uygulamaları

Dünyanın önde gelen ödeme platformları idempotency mekanizmalarını farklı yaklaşımlarla uygulamaktadır. Aşağıda bu şirketlerin uygulamalarının karşılaştırmalı analizi sunulmaktadır.

Şirket	Header Adı	TTL	Storage	Key Format
Stripe	Idempotency-Key	24 saat	Redis + DB	≤255 char
PayPal	PayPal-Request-Id	72 saat	Redis	UUID
Adyen	Idempotency-Key	24 saat	Redis	UUID v4
Square	Idempotency-Key	24 saat	Redis	UUID v4
Dwolla	Idempotency-Key	24 saat	Database	UUID

3.1 Stripe'ın Yaklaşımı (Detaylı İnceleme)

Stripe, idempotency mekanizmasının endüstri standardı haline gelmesinde öncü rol oynamıştır. Yaklaşımlarının temel özellikleri şunlardır:

1. Automatic Retry: Stripe SDK'ları, network hataları durumunda otomatik retry mekanizması içerir. Bu retry'lar exponential backoff ve jitter kullanarak yapılır.

2. Response Caching: İlk isteğin sonucu (başarılı veya başarısız) 24 saat boyunca cache'lenir. Aynı key ile gelen sonraki istekler cache'den yanıtlanır.

3. Parameter Validation: Aynı key ile farklı parametreler gönderildiğinde hata döner. Bu, key'lerin yanlışlıkla yeniden kullanılmasını engeller.

4. Key Limit: Key uzunluğu maksimum 255 karakter ile sınırlandırılmıştır.

4. En İyi Pratikler ve Öneriler

4.1 İdeal Idempotency-Key Formatı

IETF standardı ve endüstri uygulamaları dikkate alındığında, aşağıdaki format önerilmektedir:

Özellik	Önerilen Değer
Header Adı	Idempotency-Key (IETF Standardı)
Key Formatı	UUID v4 (yüksek entropi, collision riski yok)
TTL	24 saat (endüstri standardı)
Hash Algoritması	SHA-256 (payload fingerprint için)
Uygulanacak Metodlar	POST ve PATCH (non-idempotent metodlar)

4.2 Kritik Fingerprinting Kuralı

Sadece idempotency key kontrolü yeterli değildir. Aynı key ile farklı payload gönderilmesi durumunda ciddi sorunlar yaşanabilir. Bu nedenle payload fingerprinting mekanizması şarttır:

YANLIŞ: Sadece Idempotency-Key kontrol edilir. Aynı key ile farklı amount gönderildiğinde ilk response döner.

DOĞRU: Key + SHA256(payload) birlikte saklanır. Aynı key, farklı payload ile geldiğinde 422 hatası döner.

4.3 Storage Seçenekleri

Idempotency key'lerin saklanması için iki temel yaklaşım bulunmaktadır:

Redis-Based (Önerilen)

• Avantajlar: Yüksek performans, native TTL desteği, distributed sistemlerde merkezi kontrol

• Dezavantajlar: Ek altyapı gereksinimi, persistence konfigürasyonu gerekli

• Ne Zaman Kullanılmalı: Yüksek trafik, microservice mimarisi, fintech uygulamaları

Database-Based

• Avantajlar: ACID garantisi, persistence, mevcut altyapı kullanımı

• Dezavantajlar: Daha yavaş, scheduled cleanup gerekli

• Ne Zaman Kullanılmalı: Düşük-orta trafik, monolith uygulamalar, basit çözüm ihtiyacı

5. Uygulama Mimarisi

5.1 İstek Akış Diyagramı

Tipik bir idempotent istek akışı aşağıdaki adımlardan oluşur:

1. Key Extraction: Filter/Interceptor katmanında Idempotency-Key header'ı okunur

2. Validation: Key formatı doğrulanır (UUID v4 vb.)

3. Lookup: Redis/Database'de key aranır

4. Fingerprint Check: Key bulunduysa, payload hash'i karşılaştırılır

5. Processing: Key yeni ise iş mantığı çalıştırılır

6. Storage: Key, fingerprint ve response saklanır

7. Response: Yeni veya cached response döndürülür

5.2 Senaryolar ve Beklenen Davranışlar

Senaryo 1: İlk İstek (Normal Akış)

Client yeni bir UUID ile POST isteği gönderir. Sunucu key'i ilk kez görür, işlemi yapar, response'u cache'ler ve 201 Created döner.

Senaryo 2: Retry (Aynı Key + Aynı Payload)

Client aynı key ve aynı payload ile tekrar istek gönderir. Sunucu key'i bulur, fingerprint eşleşir. İşlem tekrar yapılmaz, cached response döner.

Senaryo 3: Conflict (Aynı Key + Farklı Payload)

Client aynı key ile farklı payload gönderir. Sunucu key'i bulur ancak fingerprint eşleşmez. 422 Unprocessable Content hatası döner. Client yeni UUID üretmelidir.

Senaryo 4: Concurrent Request

Aynı key ile eşzamanlı iki istek gelir. İlk istek işlenirken ikinci istek 409 Conflict alır. Client bekleyip retry yapmalıdır.

6. Güvenlik Değerlendirmeleri

IETF standardı, idempotency uygulamalarında dikkat edilmesi gereken güvenlik risklerini tanımlamaktadır:

6.1 Injection Saldırıları

Eğer sunucu idempotency key'i validate etmeden cache lookup yaparsa, kötü niyetli client'lar injection saldırıları gerçekleştirebilir. Her zaman key formatı doğrulanmalıdır.

6.2 Data Leak Riskleri

Düşük entropi key'ler (örn: sıralı sayılar) kullanıldığında, saldırganlar diğer kullanıcıların key'lerini tahmin edip cached response'larına erişebilir. Bu nedenle UUID v4 gibi yüksek entropi formatları zorunludur.

6.3 Önerilen Güvenlik Önlemleri

1. Key formatını publish edin ve her istekte validate edin

2. Composite key kullanın: idempotency_key + user_id + resource_type

3. Rate limiting uygulayın

4. Audit logging yapın

7. Sonuç ve Öneriler

Idempotency-Key header, modern API tasarımında kritik bir bileşendir. Özellikle finansal işlemler, ödeme sistemleri ve veri tutarlılığının önemli olduğu uygulamalarda vazgeçilmezdir.

Özet Öneriler

1. IETF Standardını Takip Edin: Idempotency-Key header adını kullanın

2. UUID v4 Kullanın: Güvenlik ve uniqueness için

3. Fingerprinting Uygulayın: SHA-256 ile payload hash'i saklayın

4. 24 Saat TTL: Endüstri standardı

5. Response Caching: Hem başarılı hem başarısız yanıtları saklayın

6. Dokümantasyon: API kullanıcılarına idempotency gereksinimlerini açıkça belirtin

Kaynaklar

• IETF Draft: draft-ietf-httpapi-idempotency-key-header-07

• MDN Web Docs: Idempotency-Key Header

• Stripe Documentation: Idempotent Requests

• Stripe Blog: Designing Robust APIs with Idempotency

• Brandur Leach: Implementing Idempotency Keys in Postgres