Idempotency

Ağ, başarılı bir isteğin yanıtını yolda kaybedebilir. Tekrarı güvenli kılmak için her yazma çağrısı bir X-Idempotency-Key başlığı taşır; aynı anahtarla gelen tekrar yeniden çalışmaz, ilk yanıtı geri alır.

Kurallar

Her yazmada zorunlu. Başlık olmadan (ya da 128 karakterden uzunsa) POST /shipment-requests, PATCH /shipment-requests/{id}, POST /shipment-requests/{id}/cancel ve POST /deals/{id}/documents 400 ve Integration.IdempotencyKeyRequired alır.
1 ile 128 karakter, sizin seçtiğiniz. Kendi kaydınızdan türetin, örneğin <kayıt-no>-create; böylece yeniden başlatmadan sonraki tekrar da aynı anahtarı gönderir.
24 saat hatırlanır; çağrıyı yapan API anahtarı, yöntem ve yol başına. Bu süre içindeki tekrar yeniden çalışmaz: ilk yanıt aynı durum kodu, gövde ve ETag ile, X-Idempotency-Replayed: true başlığıyla döner.
İstek karşılaştırılır. Bir anahtar tek bir isteğe aittir. Aynı rotada aynı anahtarla farklı bir istek 422 ve Integration.IdempotencyKeyReused alır, hiçbir şey çalışmaz. “Aynı istek”, oluşturma, güncelleme ve iptalde aynı JSON demektir: boşluklar, alan adlarının sırası ve büyük küçük harfi, bir sayının yazılışı (5000, 5000.0 ve 5e3 tek bir sayıdır) ve metadata anahtarlarının sırası fark etmez; bir değer, metadata anahtarının büyük küçük harfi dahil, fark eder. Yüklemede aynı dosya (içeriğiyle), aynı kategori (büyük küçük harf fark etmez), aynı dosya adı ve aynı dosya türü (charset gibi parametreler hariç) demektir; multipart sınırı fark etmez. Yeni bir istek için yeni bir anahtar kullanın.
Yalnız kesinleşmiş yanıtlar saklanır. Başarılar ve istemci hataları (4xx) tekrar edilir; 5xx saklanmaz, sunucu hatasından sonraki tekrar gerçekten yeniden çalışır.
Anlık durumlar saklanmaz. 412 (talep siz okuduktan sonra değişti) ve 429 (bir hak doldu) hiçbir zaman saklanmaz: yeniden okuduktan ya da bekledikten sonra aynı anahtarla tekrarlayın, tekrar gerçekten çalışır. API isteğinizi okumadan önce verilen ret de (JSON olmayan ya da çok büyük gövde, eksik kapsam) saklanmaz: düzeltip aynı anahtarla tekrarlayın.
Aynı anda gelirse. İlk çağrı hâlâ işlenirken gelen tekrar 409 ve Retry-After: 1 alır. Bir saniye sonra aynı anahtarla tekrarlarsanız ilk çağrının yanıtını alırsınız.
Yeni anahtarlar için günlük hak. Her API anahtarı UTC günü başına 5.000 yeni idempotency anahtarı kullanabilir. Hak dolunca yazma çağrısı 429, Idempotency.DailyLimit ve UTC gece yarısına kadar süren bir Retry-After alır, hiçbir şey çalışmaz: o süreden sonra aynı anahtarla tekrarlayın. O gün yanıtlanmış bir anahtarın tekrarı sayılmaz ve her zamanki gibi tekrar edilir.
Bütünüyle saklanamayacak kadar büyük yanıt. 256 KB’tan büyük bir yanıt ya da anahtarın yanıtlar için günlük saklama hakkı (8 MB, yaklaşık 2.000 olağan yanıt) dolduktan sonra verilen bir yanıt yalnızca durum koduyla saklanır. Tekrar yine yeniden çalışmaz: bu durum kodunu X-Idempotency-Replayed: true ve X-Idempotency-Body-Omitted: true başlıklarıyla, gövdesiz alır. Gerisi için kaydı okuyun; örneğin oluşturmadan sonra GET /shipment-requests?externalReference=..., yüklemeden sonra GET /deals/{id}/documents.

HTTP/1.1 409 Conflict
Retry-After: 1
Content-Type: application/json

{ "status": 409, "title": "Conflict", "detail": "The same request is already being processed." }

Her değişiklik için bir anahtar kullanın: güncellemede anahtarı kaydınızdan ve değişiklikten türetin (örneğin <kayıt-no>-update-<n>), böylece sonraki değişiklik yeni bir anahtar alır. Diğer POST rotaları (deneme alanı ilerletme, belirteç adresi) başlığı kabul eder ama zorunlu tutmaz.

Idempotency ve externalReference birlikte

İkisi farklı şeylere karşı korur:

	`X-Idempotency-Key`	`externalReference`
Neye karşı	Aynı HTTP çağrısının iki kez gönderilmesi	Aynı iş kaydının iki kez gönderilmesi
Süresi	24 saat	Talep var oldukça
Tekrar ne alır	İlk yanıt, tekrar edilmiş hâliyle (`X-Idempotency-Replayed: true`)	İlk talebin `requestId` değeriyle `409`

Bu yüzden her hatadan sonraki güvenli tekrar şudur: aynı X-Idempotency-Key ve aynı externalReference. İlk çağrı talebi oluşturduysa yanıtını (ya da onu gösteren bir 409) geri alırsınız; asla ikinci bir talep açılmaz. Bkz. externalReference.

Kayıtta ne tutulur

Çağrı kaydı her çağrıyla birlikte idempotency anahtarının kendisini değil, özetini tutar; böylece Sahip ya da Yöneticiniz bir tekrarı tekrar ettiği çağrıyla eşleştirebilir.