Idempotency

AstroWay API’nin tüm endpoint’leri doğası gereği idempotent’tir: aynı girdi her zaman aynı çıktıyı verir, yan etkisi yoktur (kredi düşümü ve kullanım kaydı hariç).

Bu, ağ hatalarında retry yapmanın güvenli olduğu anlamına gelir. Ancak tekrarlanan isteğin krediyi iki kez düşmemesi için Idempotency-Key başlığını göndermeniz gerekir.

Nasıl kullanılır

POST /v1/chart HTTP/1.1
X-Api-Key: aw_live_...
Idempotency-Key: 01HXY2A7ZM0ABCDEF
Content-Type: application/json

{ "datetime": "1990-07-14T14:30:00", ... }

Idempotency-Key, en fazla 64 karakterlik, her mantıksal işlem için benzersiz, serbest biçimli bir dizedir. Önerilen: ULID veya UUID v4.

Garantiler

• Bu anahtarla yapılan ilk istekten sonraki 24 saat boyunca, aynı anahtarla gelen tekrar istekleri yeniden hesaplama yapılmadan ve kredi düşülmeden aynı yanıtı döndürür.
• İsteğin gövdesi orijinalinden farklıysa idempotency_key_reuse koduyla 409 Conflict döner.
• 24 saat sonra anahtar unutulur; aynı anahtarla gelen yeni bir istek normal bir istek olarak işlenir.

Not

Idempotency bir önbellek değil, ağ kesintilerinde çift kredi düşümüne karşı bir korumadır. Önbellekleme için doğal X-Cache mekanizmasını kullanın (5 dakika, bkz. Krediler ve limitler).

Ne zaman gerekir

• Retry’ın dış bir sistemden geldiği webhook handler’larında (örneğin bir ödeme sağlayıcısı veya CRM, sizin ayrıştırıp hesaplama yaptığınız bir olay gönderdiğinde)
• Retry’ın hata durumunda standart davranış olduğu arka plan job’larında
• Bir testin yeniden çalışabileceği CI/CD pipeline’larında

“Kullanıcı düğmeye bastı → harita gösterildi” gibi olağan etkileşimlerde idempotency gerekmez: kullanıcı sonucu zaten görür, tekrarlanan tıklamalar genellikle olmaz.

Ne zaman kullanılmamalı

• Aynı isteklerde kredi tasarrufu yapmak için anahtar koymayın: bunun için X-Cache var (ücretsiz, 5 dakika)
• Anahtarı hash(body) ile üretmeyin: bu durumda Idempotency-Key’in varsayılan davranışını kaybedersiniz (gövde farklı olduğunda tekrar eden 409)