- Konu sahibi
- #1
API isteklerinde idempotency nedir?
API isteklerinde idempotency, aynı isteğin birden fazla uygulanmasının sunucuda amaçlanan etkisinin tek uygulamayla aynı kalmasıdır. Yanıt kodu veya gövdesi her denemede aynı olmak zorunda değildir. Örneğin ödeme oluşturma isteği iki kez ulaşsa bile iki ayrı ödeme yerine aynı işlem sonucu döndürülür. Amaç isteğin hiç tekrarlanmaması değil, güvenli biçimde tekrarlanabilmesidir.
Nasıl çalışır?
Idempotency-key kullanan bir POST tasarımında istemci, tekrar denemek istediği mantıksal işlem için benzersiz bir anahtar üretir ve bunu isteğe ekler. Sunucu bu anahtarı kaydeder. Aynı anahtarla gelen ilk istek başarıyla tamamlanmışsa sunucu işlemi yeniden yapmadan önceki sonucu döndürür. İlk istek hâlâ işleniyorsa sunucu ikinci isteği bekletebilir veya işlemin devam ettiğini bildirebilir.
Örneğin istemci yeni sipariş oluştururken şu başlığı kullanabilir:
Kod:
Idempotency-Key: siparis-7f3a9c2eAşağıdaki şematik örnek gerçek bir endpoint değildir; başlık adı ve sunucu davranışı API sözleşmesinde desteklenmelidir:
Kod:
POST /orders
Idempotency-Key: siparis-7f3a9c2e
Content-Type: application/json
{"product_id":"example-product","quantity":1}İstemci yanıt alamazsa aynı gövde ve aynı anahtarla isteği tekrarlar. Sunucu anahtarı ve istek gövdesini eşleştirirse siparişi ikinci kez oluşturmaz; daha önce ürettiği sipariş sonucunu döndürür.
Burada önemli ayrım şudur: Benzersiz anahtar her HTTP isteğinde rastgele değiştirilirse sunucu bunları yeni işlemler sanabilir. Yeniden deneme sırasında aynı mantıksal işlem için aynı anahtar korunmalıdır. Yeni bir sipariş oluşturulacaksa yeni anahtar kullanılmalıdır.
Hangi yöntemlerde ne anlama gelir?
HTTP yönteminin idempotent kabul edilmesi, uygulamanızdaki her işlemin otomatik olarak güvenli olduğu anlamına gelmez. İşlemin etkisini ve API sözleşmesini ayrıca tasarlamak gerekir.
| İşlem | Tipik yaklaşım | Dikkat edilmesi gereken nokta |
|---|---|---|
| PUT | Belirli kaynağı verilen duruma getirir | Aynı gövdeyle tekrarlandığında aynı son durumu üretmelidir |
| DELETE | Kaynağın silinmiş olmasını hedefler | İkinci çağrının bulunamayan kaynak yanıtı vermesi sözleşmeye göre ele alınmalıdır |
| POST | Genellikle yeni işlem başlatır | Güvenli otomatik yeniden deneme isteniyorsa anahtar veya eşdeğer mekanizma tasarlanır |
PUT ve DELETE çoğu tasarımda aynı son durumu hedeflediği için tekrar çağrılmaya daha uygundur. Ancak sunucunun her çağrıda bildirim göndermesi, sayaç artırması veya harici bir iş başlatması gibi yan etkileri varsa yalnızca HTTP yöntemine güvenilmemelidir.
Uygulanabilir tasarım adımları
- Tekrarlanması maliyetli olan işlemleri belirleyin. Ödeme, sipariş, üyelik oluşturma, kredi kullanma ve dış servise iş gönderme gibi işlemler önceliklidir.
- İstemcinin her mantıksal işlem için bir idempotency anahtarı üretmesini sağlayın. Yeniden denemelerde anahtar değişmemeli, farklı işlemlerde yeniden kullanılmamalıdır.
- Sunucuda anahtarı işlem sonucu ile birlikte saklayın. Kayıt; anahtarı, ilgili istemci veya hesap kapsamını, istek gövdesinin kimliğini, işlem durumunu ve döndürülecek sonucu ilişkilendirmelidir.
- Aynı anahtarla gelen isteğin gövdesini ilk istekle karşılaştırın. Anahtar aynıyken gövde değişmişse isteği yeni işlem olarak çalıştırmayın; istemci hatası bildirin.
- İlk işlem devam ederken gelen tekrarı açık bir durumla yönetin. İşlemi eşzamanlı çalıştırmak yerine bekletmek, mevcut sonucu döndürmek veya istemcinin daha sonra sorgulamasını istemek seçeneklerdir.
- Aynı hesap ve anahtar için eşzamanlı iki isteğin de ilk istek sayılmasını atomik kayıt veya benzersizlik kısıtıyla önleyin. Harici ödeme/e-posta gibi etkiler yerel veritabanı işlemiyle otomatik atomik olmaz; alt sistemin işlem kimliği veya uygun outbox akışı ayrıca tasarlanır. Kalıcı kaydı ve iş etkisini aynı güvenilir işlem sınırında koruyun. Anahtar kaydedilip sipariş oluşturulmadan işlem kesilirse sonraki denemenin ne yapacağı önceden tanımlanmalıdır.
- Başarılı yanıtı, bilinen iş hatalarını ve belirsiz zaman aşımını ayrı ele alın. Zaman aşımında sunucu işlemi tamamlamış olabilir; istemci doğrudan yeni anahtar üretmek yerine aynı anahtarla tekrar denemeli veya işlem durumunu sorgulamalıdır.
Somut karar örneği
Bir ödeme API'sinde istemci, istek gönderildikten sonra bağlantının koptuğunu varsayalım. Sunucu ödemeyi almış fakat yanıt istemciye ulaşmamış olabilir. İstemci aynı anahtarla tekrar gönderirse sunucu önceki ödeme sonucunu döndürür. İstemci yeni anahtar kullanırsa aynı kart veya hesap için ikinci bir ödeme başlatma riski doğar.
Aynı anahtarla farklı tutar gönderilmesi ise kabul edilmemelidir. Bu durum genellikle istemcinin anahtarı yanlış kapsamda kullandığını veya yeniden denemeden önce isteği değiştirdiğini gösterir. Sunucu işlemi sessizce birleştirmek yerine açık bir çakışma yanıtı vermelidir.
Sık yapılan hatalar
- Anahtarı yalnızca uygulama belleğinde tutmak: Sunucu yeniden başlatıldığında veya birden fazla sunucu kullanıldığında kayıt kaybolabilir.
- Anahtarı istek gövdesinden bağımsız kabul etmek: Aynı anahtarın farklı işlem için kullanılması veri bütünlüğünü bozabilir.
- Yalnız başarılı sonuçları kaydetmek: İşlenmiş fakat yanıtı kaybolmuş bir işlemin yeniden çalıştırılması yine çift etki oluşturabilir.
- Kısa ve belirsiz bir saklama politikası kullanmak: Anahtar kaydı silindikten sonra gelen gecikmiş yeniden deneme yeni işlem sanılabilir. Saklama süresi işlem ve gecikme modeline göre belirlenmelidir.
- İstemcinin her hatada yeni anahtar üretmesine izin vermek: Bu, idempotency mekanizmasını etkisiz bırakır.
İdempotency, işlemin tüm yan etkilerini otomatik olarak ortadan kaldırmaz. Veritabanı kaydı oluşturma, stok düşme, e-posta gönderme ve harici ödeme servisini çağırma gibi her yan etki için aynı işlem kimliğinin alt sistemlere de taşınması gerekebilir.
Sık sorulan sorular
İdempotency anahtarı kullanıcı başına mı, işlem başına mı üretilmelidir?
Genellikle işlem başına üretilmelidir. Sunucu ayrıca anahtarı hesap, kullanıcı veya yetkili istemci kapsamına bağlayarak başka bir aktörün aynı anahtarla kayıt aramasını önleyebilir.
