Idempotent API Tasarımı 2026: Tekrarlı İstekleri Güvenle Yönetme

İdempotent API Nedir ve Neden Vazgeçilmezdir?

İdempotent bir API, aynı isteğin bir kez ya da birden çok kez gönderilmesi durumunda sistemin durumunu aynı sonuca getiren API’dir. Doğrudan yanıt: bir ödeme isteği ağ zaman aşımı nedeniyle başarısız göründüğünde istemci tekrar dener; idempotentlik olmadan bu, müşteriden iki kez para çekmek anlamına gelir. İdempotent tasarım, her değiştirici isteğe benzersiz bir idempotency anahtarı ekleyerek sunucunun aynı isteği yalnızca bir kez işlemesini garanti eder. İkinci ve sonraki tekrarlar, yeni bir işlem yapmadan ilk işlemin saklanmış sonucunu döndürür. Bu, dağıtık sistemlerin doğasında var olan ağ belirsizliğine karşı temel bir güvenlik mekanizmasıdır.

Dağıtık sistemlerde ağ hataları kaçınılmazdır ve bir isteğin başarısız görünmesi, gerçekte başarısız olduğu anlamına gelmez; yanıt yolda kaybolmuş olabilir. İstemcinin yeniden denemesi (retry) güvenilirlik için zorunludur, ancak yeniden deneme yalnızca sunucu idempotent ise güvenlidir. Bu nedenle idempotentlik, retry mekanizmasının ön koşuludur; biri olmadan diğeri tehlikelidir.

Sorunun kökeni, istemcinin asla emin olamadığı belirsizlik durumudur. İstemci bir istek gönderir ve zaman aşımı alır; bu noktada üç olasılık vardır. İstek sunucuya hiç ulaşmamış olabilir, sunucu işlemiş ama yanıt dönüş yolunda kaybolmuş olabilir, ya da sunucu işlemin ortasında çökmüş olabilir. İstemci bu üçünü ayırt edemez. Doğru davranış yeniden denemektir, çünkü gerçekten başarısız olduysa retry işlemi tamamlar. Ancak istek aslında işlendiyse ve yalnızca yanıt kaybolduysa, retry ikinci bir işlem tetikler. İdempotentlik tam olarak bu belirsizliği güvenli kılar: sunucu, aynı işlemin tekrar isteğini tanır ve yeni bir yan etki üretmeden ilk sonucu döndürür. Böylece istemci, sonucu kesin olarak öğrenene kadar güvenle tekrar deneyebilir.

HTTP Metotları ve Doğal İdempotentlik

HTTP metotlarının bir kısmı tanım gereği idempotenttir, bir kısmı değildir. MDN HTTP metotları referansı her metodun idempotentlik ve güvenlik (safety) özelliklerini tanımlar. Aşağıdaki tablo bu özellikleri özetler.

Bu tablo gösteriyor ki asıl zorluk POST ve bazı PATCH istekleridir; bunlar doğal olarak idempotent değildir çünkü her çağrıda yeni bir yan etki (yeni kayıt, yeni ödeme) üretirler. PUT ve DELETE doğal olarak idempotenttir: bir kaynağı aynı değere iki kez set etmek veya zaten silinmiş bir kaynağı tekrar silmek son durumu değiştirmez. Pratikte mühendislik çabası, POST gibi doğal idempotent olmayan işlemleri idempotency anahtarıyla idempotent hale getirmeye odaklanır.

İdempotency Anahtarı: Çalışma Mekanizması

İdempotency anahtarı, istemcinin her benzersiz işlem için ürettiği ve genellikle Idempotency-Key HTTP başlığında gönderdiği eşsiz bir tanımlayıcıdır (tipik olarak bir UUID). Sunucu bu anahtarı kullanarak isteğin daha önce işlenip işlenmediğini kontrol eder. Stripe’ın idempotency dokümantasyonu bu yaklaşımın endüstri standardı uygulamasıdır.

İşleyiş şu adımları izler:

1. İstemci her yeni işlem için benzersiz bir anahtar üretir ve istekle gönderir.
2. Sunucu anahtarı bir depoda (Redis, veritabanı) arar.
3. Anahtar yoksa: isteği işler, sonucu anahtarla birlikte saklar ve döndürür.
4. Anahtar varsa ve işlem tamamlanmışsa: yeni işlem yapmadan saklanan sonucu döndürür.
5. Anahtar varsa ama işlem devam ediyorsa: eşzamanlı tekrarı kilitler veya bekletir.

Bu mekanizmanın kritik detayı, anahtar-sonuç eşleşmesinin atomik olarak saklanmasıdır; aksi halde iki eşzamanlı tekrar aynı anda “anahtar yok” görüp her ikisi de işlem yapabilir. Bu yarış durumu (race condition), benzersiz kısıt (unique constraint) veya dağıtık kilit ile önlenir. İdempotentlik, mesaj kuyrukları söz konusu olduğunda Outbox Pattern’in en-az-bir-kez teslimatıyla doğrudan tamamlayıcıdır.

İdempotency anahtarının yaşam döngüsü boyunca geçtiği durumlar net biçimde tanımlanmalıdır. Aşağıdaki tablo bir anahtarın olası durumlarını ve sunucu davranışını gösterir.

Anahtar Yönetimi: Saklama, Süre ve Çakışma

İdempotency anahtarlarının nasıl saklanacağı ve ne kadar süre tutulacağı, tasarımın güvenilirliğini belirler. Aşağıdaki tablo anahtar deposu seçeneklerini karşılaştırır.

Anahtarlar sonsuza dek saklanamaz; bir saklama süresi (TTL) tanımlanır. Tipik olarak 24 saat ile 7 gün arasında bir pencere, retry’ların gerçekleşeceği makul süreyi kapsar. TTL dolduktan sonra aynı anahtarın tekrar kullanılması yeni bir işlem olarak değerlendirilir. Önemli bir kenar durumu, aynı anahtarla farklı istek gövdesi gönderilmesidir; bu durumda sunucu, gövde parmak izini (request fingerprint) anahtarla birlikte saklayıp uyuşmazlıkta hata döndürmelidir; aksi halde istemci hatası sessizce yanlış sonuca yol açar.

Anahtar deposunun seçimi, sistemin ölçeğine ve güvenilirlik gereksinimine bağlıdır. Yüksek hacimli ve kısa TTL’li senaryolarda Redis, yerel TTL desteği ve çok yüksek hızıyla doğal tercihtir; anahtar otomatik olarak süresi dolunca temizlenir ve ek temizlik işi gerekmez. Buna karşılık, denetim (audit) gereksinimi olan veya anahtarların kalıcı kaydının tutulması gereken finansal sistemlerde ilişkisel veritabanı tercih edilir; bu durumda süresi dolan kayıtları temizleyen periyodik bir iş çalıştırılır. Çok bölgeli (multi-region) dağıtımlarda ise dağıtık bir anahtar-değer deposu, anahtarların tüm bölgelerde tutarlı görünmesini sağlar. Hangi depo seçilirse seçilsin, kritik kural değişmez: anahtarın yazımı ile işlemin yürütülmesi atomik bir bütün olarak ele alınmalı, böylece yarış durumları ve kısmi başarısızlıklar tutarsızlık üretmemelidir.

İstemci tarafının sorumluluğu da göz ardı edilmemelidir. İdempotentliğin işe yaraması için istemcinin her mantıksal işlem için bir anahtar üretip bu anahtarı tüm yeniden denemeler boyunca sabit tutması gerekir. Sık yapılan bir hata, her retry’da yeni bir anahtar üretmektir; bu durumda sunucu her isteği yeni bir işlem sanar ve idempotentlik tamamen devre dışı kalır. Bu nedenle anahtar, işlem niyetinin oluştuğu anda bir kez üretilmeli ve istek başarılı yanıt alana kadar değişmeden tekrar kullanılmalıdır.

• TTL seçimi: Retry penceresini kapsayacak kadar uzun, depoyu şişirmeyecek kadar kısa.
• Gövde parmak izi: Aynı anahtar + farklı gövde durumunda 422 benzeri hata döndür.
• Atomik kayıt: Anahtar yazımı benzersiz kısıt veya dağıtık kilitle yarış durumundan korunur.

Eşzamanlılık, Yarış Durumları ve Durum Kodları

İdempotentlik tasarımının en zorlu kısmı eşzamanlı tekrar istekleridir. İki istek neredeyse aynı anda gelirse, ikisi de anahtarı “yok” görüp işlem başlatabilir. Bu yarış durumunu önlemek için anahtar kaydı, asıl işlemden önce ve atomik olarak yapılmalıdır. Pratikte istek geldiğinde önce anahtar “işleniyor” durumuyla benzersiz kısıt altında yazılır; ikinci istek bu kısıta takılır ve ya bekler ya da “işlem devam ediyor” yanıtı alır.

Bu yarış durumu pratikte sıkça gözden kaçar çünkü tek kullanıcılı testlerde asla ortaya çıkmaz; yalnızca yük altında, aynı anahtarlı iki isteğin milisaniyeler arayla geldiği üretim koşullarında patlak verir. Hatalı bir uygulamada her iki istek de “anahtar yok” görür, ikisi de ödemeyi işler ve müşteriden iki kez para çekilir. Doğru çözüm, anahtarın yazımını veritabanı seviyesinde benzersiz kısıtla korumaktır: ilk istek anahtarı yazar, ikinci istek aynı anahtarı yazmaya çalışınca kısıt ihlali alır ve bu ihlal, sunucuya “bu işlem zaten devam ediyor” sinyali olarak yorumlanır. Yüksek eşzamanlılık gereken sistemlerde dağıtık bir kilit (örneğin Redis tabanlı) ek bir koruma katmanı sağlar. Anahtar yazımının asıl yan etkiden önce ve atomik olması, bu desenin pazarlık edilemez kuralıdır.

Bir kritik tasarım kararı da yan etkinin ne zaman kalıcı sayılacağıdır. İşlem birden çok adımdan oluşuyorsa (önce ödeme al, sonra sipariş oluştur, sonra bildirim gönder) ve ortada çökme yaşanırsa, anahtar “tamamlandı” olarak işaretlenmemelidir; aksi halde tekrar isteği eksik bir işlemi tamamlanmış sanarak yanlış sonuç döndürür. Bu nedenle anahtar bir durum makinesiyle yönetilir: başladı, işleniyor ve tamamlandı durumları net biçimde ayrılır ve yalnızca tüm yan etkiler kalıcı olduğunda tamamlandı işaretlenir.

Durum kodlarının tutarlılığı da kritiktir. İlk başarılı işlem 201 Created dönerken, aynı anahtarla gelen tekrar da aynı 201 ve aynı gövdeyi döndürmelidir; farklı kod döndürmek istemci mantığını bozar. Devam eden işlem için 409 Conflict, gövde uyuşmazlığı için 422 Unprocessable Entity yaygın seçimlerdir. IETF Idempotency-Key başlığı taslağı, bu davranışları standartlaştırma çabasını temsil eder ve uzun vadeli referans olarak izlenmelidir. İdempotentlik ayrıca sistem gözlemlenebilirliği ile birlikte izlendiğinde tekrar oranları ölçülebilir hale gelir.

İdempotentlik gereksinimi, işlemin yan etkisinin niteliğine göre değişir. Aşağıdaki tablo yaygın alan işlemlerini ve önerilen yaklaşımı özetler.

Mesaj tabanlı işlemlerde idempotentlik, Outbox Pattern ile transactional messaging yaklaşımının tamamlayıcısıdır; tüketici tarafı idempotent olmadan en-az-bir-kez teslimat mükerrer işleme üretir.

Tipik Sorunlar ve Çözümleri

İdempotent API tasarlarken ekipler tekrar eden hatalara düşer. Aşağıdaki maddeler en yaygın tuzakları ve doğrudan çözümlerini özetler.

• Yarış durumu: Eşzamanlı tekrarlar anahtarı aynı anda “yok” görüyor; anahtar kaydı benzersiz kısıt veya dağıtık kilitle atomik yapılır.
• Aynı anahtar, farklı gövde: İstemci hatası sessizce yanlış sonuç üretir; gövde parmak izi saklanıp uyuşmazlıkta hata döndürülür.
• Anahtar deposu sonsuz büyüme: TTL’siz saklama depoyu şişirir; 24 saat-7 gün arası TTL ve otomatik temizlik uygulanır.
• Tutarsız durum kodu: Tekrar isteği ilkinden farklı kod dönüyor; saklanan sonuç aynı kod ve gövdeyle aynen döndürülür.
• İstemcinin anahtar üretmemesi: Aynı işlem için her seferinde yeni anahtar üretiliyor; anahtar işlem başına bir kez üretilip retry’larda korunur.
• Yan etkilerin kısmen tamamlanması: İşlem ortada çökerse anahtar “tamamlandı” işaretlenmemeli; durum makinesiyle (başladı/tamamlandı) yönetilir.

Sonuç

İdempotent API tasarımı, dağıtık sistemlerin doğasındaki ağ belirsizliğine karşı temel bir güvenlik katmanıdır ve özellikle ödeme, sipariş ve kaynak oluşturma gibi yan etkili işlemlerde vazgeçilmezdir. GET, PUT ve DELETE doğal olarak idempotentken, POST gibi işlemler idempotency anahtarıyla idempotent hale getirilmelidir. Anahtar atomik olarak saklanmalı, makul bir TTL ile sınırlanmalı, gövde parmak iziyle korunmalı ve tekrar istekleri ilk isteğin sonucunu tutarlı durum koduyla döndürmelidir. İdempotentlik, güvenli yeniden denemenin ön koşulu olarak, retry mekanizmaları ve Outbox Pattern gibi mesajlaşma desenleriyle birlikte uygulandığında uçtan uca güvenilir bir sistem oluşturur. 2026’da güvenilir bir API, idempotent olmadan eksiktir.

Sıkça Sorulan Sorular