Idempotency

Ağ güvenilir değildir. Bir POST gönderirsin, yanıt gelmez — istek sunucuya ulaştı mı, ulaşmadı mı bilemezsin. Yeniden gönderirsen ikinci bir kayıt oluşabilir; göndermezsen hiç oluşmamış olabilir.

Idempotency-Key bu belirsizliği kaldırır.

#Kullanımı

curl -X POST "https://acme.crm.blesyum.app/api/crm/public/v1/contacts" \
  -H "Authorization: Bearer blsk_..." \
  -H "Idempotency-Key: 9f2c1e40-6b3d-4a1f-9c2e-7d5b8a1f3c4e" \
  -H "Content-Type: application/json" \
  -d '{"email":"ayse@ornek.com","name":"Ayşe Yılmaz"}'

Aynı anahtarla ikinci kez gönderirsen: yeni kayıt oluşmaz, ilk isteğin yanıtı aynen döner. Aynı durum kodu, aynı gövde.

#Anahtarı sen üretirsin

Anahtar senin ürettiğin, benzersiz bir değerdir (UUID iyi bir seçimdir). Doğru desen: anahtarı isteği kurarken bir kez üret ve tüm yeniden denemelerde aynısını kullan.

const idemKey = crypto.randomUUID();

async function kisiOlustur(govde: unknown) {
  // Yeniden denemelerin HEPSİ aynı anahtarı taşır — yoksa idempotency'nin
  // hiçbir anlamı kalmaz.
  return istekAt(url, {
    method: "POST",
    headers: { "Idempotency-Key": idemKey, "Content-Type": "application/json" },
    body: JSON.stringify(govde),
  });
}

#Aynı anahtar, farklı gövde → 409

Sunucu isteğin bir parmak izini tutar: metot + yol + gövdenin özeti. Aynı anahtarla farklı bir gövde gönderirsen 409 alırsın:

{ "error": { "code": "CORE-REQ-0005",
             "message": "Bu idempotency anahtarı farklı bir istekle kullanılmış." } }

Bu bir koruma: anahtarı yanlışlıkla yeniden kullanmak, iki farklı işlemden birinin sessizce kaybolması demek olurdu.

#Süre

Kayıtlar 24 saat saklanır. Bu süre içinde aynı anahtarla gelen istek tekrar oynatılır; sonrasında anahtar serbest kalır.

#Yarım kalan istek

İlk istek işlenirken çökme olursa kayıt "kilitli" kalır. Bu kilit 60 saniye sonra otomatik serbest bırakılır ve istek yeniden çalıştırılabilir — kalıcı bir 409 duvarı oluşmaz.

#Hangi uçlarda

Yan etkisi olan tüm yazma uçlarında kullanabilirsin. GET isteklerinde anlamı yoktur (zaten idempotenttirler) ve yok sayılır.