Idempotency (Tekrarlanan İstek Koruması)

Idempotency, aynı isteğin birden fazla kez gönderilmesi durumunda yalnızca bir kez işlenmesini sağlayan bir mekanizmadır. Bu özellik, özellikle ağ sorunları veya zaman aşımı durumlarında mükerrer kayıtların oluşmasını önler.

Ne Zaman Kullanılmalı?

Idempotency özelliği aşağıdaki senaryolarda kritik öneme sahiptir:

Senaryo	Açıklama
Ağ Zaman Aşımı	İstek sunucuya ulaştı ve işlendi, ancak yanıt istemciye ulaşamadı. İstemci isteği tekrar gönderdiğinde mükerrer kayıt oluşabilir.
Bağlantı Kesintisi	İstek gönderilirken bağlantı koptu, isteğin işlenip işlenmediği belirsiz.
Yeniden Deneme (Retry)	Otomatik retry mekanizması olan sistemlerde aynı isteğin birden fazla kez gönderilmesi.

Örnek Senaryo: Bir gönderi oluşturma isteği gönderdiniz. Sunucu gönderiyi oluşturdu ancak yanıt dönerken bağlantı koptu. Sisteminiz isteği tekrar gönderdi. Idempotency olmadan iki ayrı gönderi oluşurdu.

Nasıl Kullanılır?

Idempotency özelliğini kullanmak için isteğinize X-Idempotency-Key header'ı eklemeniz yeterlidir.

Header	Değer	Zorunluluk
`X-Idempotency-Key`	Benzersiz string (UUID, sipariş numarası vb.)	OPSİYONEL

Not: Bu header gönderilmezse idempotency kontrolü yapılmaz ve istek normal şekilde işlenir.

Örnek İstek

curl -X POST "{{BASE_URL}}/api/v1/consignments" \
  -H "Content-Type: application/json" \
  -H "APIKEY: {{APIKEY}}" \
  -H "X-Idempotency-Key: order-12345-shipment-001" \
  -d '{
    "provider_id": 1,
    "preference": 0,
    ...
  }'

Davranış

İlk İstek

İstek normal şekilde işlenir ve başarılı yanıt cache'lenir.

Aynı Key ile Tekrar İstek

Belirli bir süre içinde aynı X-Idempotency-Key ile tekrar istek geldiğinde:

İstek tekrar işlenmez
Önceki başarılı yanıt döndürülür

Hatalı Yanıtlar

Eğer ilk istek hata ile sonuçlandıysa (HTTP 4xx veya 5xx), yanıt cache'lenmez. Bu sayede hatalı istekler düzeltilerek tekrar gönderilebilir.

Yanıt Header'ları

Idempotency aktif olan başarılı isteklerde aşağıdaki header'lar yanıta eklenir:

Header	Açıklama
`X-Idempotency-Key`	Gönderilen idempotency key değeri
`X-Idempotency-Stored-At`	Yanıtın cache'lendiği zaman (Unix timestamp)

Destekleyen Endpoint'ler

Aşağıdaki endpoint'ler idempotency özelliğini desteklemektedir:

Endpoint	Metod	Açıklama
`/api/v1/consignments`	POST	Yurtiçi/Yurtdışı gönderi oluşturma
`/api/v1/consignments/multi-package`	POST	Çoklu paket gönderi oluşturma
`/api/v1/consignments/draft`	POST	Taslak gönderi oluşturma

Key Seçimi İçin Öneriler

Idempotency key seçerken aşağıdaki önerileri dikkate alın:

Öneri	Açıklama
Benzersiz olmalı	Her farklı işlem için farklı bir key kullanın
Tahmin edilebilir olmalı	Aynı işlem için her zaman aynı key'i üretebilmelisiniz
İş mantığına bağlı olmalı	Sipariş numarası, işlem ID'si gibi iş mantığınızdaki benzersiz değerleri kullanın

Önerilen Key Formatları

# Sipariş bazlı
order-{sipariş_no}-shipment

# UUID
550e8400-e29b-41d4-a716-446655440000

# Tarih + işlem bazlı
2024-01-15-order-12345

Uyarı: Rastgele üretilen key'ler (örn: her retry'da yeni UUID) idempotency amacını ortadan kaldırır. Key, aynı işlem için her zaman aynı değeri üretmelidir.