Idempotency: Aynı Request İki Kere Gelirse Ne Olur?

Uzun süre şunu varsaydım:

Bir endpoint’e bir istek gelirse,
o işlem bir kez çalışır.

Ama production’da öğrendiğim gerçek şu oldu:

👉 Aynı request iki kere gelebilir.

Gerçek Dünya Senaryoları

Aynı isteğin tekrar gelmesi sandığından çok daha yaygındır:

• Kullanıcı butona iki kere basabilir

• Network timeout olabilir

• Client retry atabilir

• Gateway tekrar deneyebilir

Problem Nerede Başlıyor?

Eğer sistem idempotent değilse,
aynı işlem iki kez çalışır.

Bu da şu riskleri doğurur:

• 💸 Çift ödeme

• 🛒 Aynı siparişin iki kez oluşması

• 📧 Tekrar eden e-postalar

• ⚠️ Veri tutarsızlığı

Idempotency Nedir?

Idempotency’nin temel mantığı şudur:

Aynı isteği kaç kere alırsam alayım, sonuç değişmemeli.

Yani:

• İlk request çalışır

• Aynı request tekrar gelirse
  👉 sistem aynı sonucu döner veya işlemi tekrar yapmaz

Nasıl Uygulanır?

Pratikte idempotency’yi şu yöntemlerle tasarlarız:

• Idempotency key kullanmak

• İşlemi benzersiz bir referansla kontrol etmek

• Database seviyesinde unique constraint koymak

• İşlemin daha önce yapılıp yapılmadığını kontrol etmek

Örnek Senaryo

Bir ödeme endpoint’i düşün:

POST /payments

Eğer kullanıcı aynı isteği 2 kez gönderirse:

• ❌ Idempotency yoksa → 2 ödeme alınır

• ✅ Idempotency varsa → sadece 1 ödeme alınır

Kritik Nokta

Özellikle şu işlemlerde:

• ödeme sistemleri

• sipariş oluşturma

• kullanıcı kaydı

• e-posta gönderimi

👉 idempotency zorunluluktur

Gerçek Dünya Gerçeği

Şunu unutma:

• Network güvenilir değildir

• Client mükemmel değildir

• Retry mekanizmaları her zaman vardır

Sonuç

Doğru API tasarımı:

👉 sadece başarılı senaryoyu değil

👉 tekrar eden senaryoyu da düşünür

Summary

This article explains idempotency in backend systems and why APIs must handle duplicate requests safely. It covers real-world failure scenarios and common implementation strategies such as idempotency keys and database constraints.