Idempotency (Tekrar Güvenli İstekler)

Ağ hataları veya zaman aşımları nedeniyle bir isteği tekrar göndermeniz gerekebilir. Idempotency, aynı isteğin yanlışlıkla iki kez işlenmesini (örneğin çift sipariş, çift ücretlendirme) önler.

Nasıl Çalışır?

Mutasyon içeren isteklere (POST, DELETE) Idempotency-Key başlığı ekleyin. Bu başlık UUID v4 biçiminde benzersiz bir değer olmalıdır:

curl -X POST https://api.rabisu.com/api/v1/orders \
  -u "rsk_live_xxx:rsks_yyy" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c2d3e-4b5a-6c7d-8e9f-0a1b2c3d4e5f" \
  -d '{ "product_id": 101, "period": "monthly" }'

Davranış:

Durum	Sonuç
Key yok	Normal işlenir (idempotency korumasız).
Key var, aynı gövde	24 saat içindeki ilk yanıt cache'ten aynen döner — işlem tekrar yürütülmez.
Key var, farklı gövde	422 idempotency_key_reuse hatası — aynı anahtar farklı içerikle kullanılamaz.

Zorunlu Olduğu Uç Noktalar

Bazı finansal / yıkıcı uç noktalarda Idempotency-Key zorunludur; eksikse 400 missing_idempotency_key döner:

• POST /orders — sipariş oluşturma
• POST /services/{id}/upgrade — kaynak yükseltme (fark faturası)
• POST /services/{id}/rebuild — işletim sistemi yeniden kurulumu
• POST /services/{id}/power/{action} — güç işlemleri
• DELETE /services/{id} — servis iptali (disk silinir)

Öneriler

• Her mantıksal işlem için kararlı (stable) bir anahtar üretin. Örneğin "servis 500 için aylık yükseltme" isteğini tekrar denerken aynı anahtarı kullanın ki çift faturalama olmasın.
• Yeni bir işlem için yeni anahtar üretin.
• Anahtarlar 24 saat boyunca saklanır; bu süre sonunda aynı anahtar yeniden kullanılabilir.