Idempotency — Hear2Text API

Neden önemli

Buradaki isteklerden yalnızca biri para harcatır: oluşturma. Yükleme biterken bağlantınız koparsa kaydı kabul edip etmediğimizi kendi tarafınızdan anlayamazsınız; körlemesine yeniden denemek ise aynı kaydı iki kez deşifre ettirir, dakikaları da iki kez faturalandırır. Bu başlık tam olarak bunun için var.

Anahtarı göndermek

Idempotency-Key başlığına benzersiz bir dize koyun — her POST /transcriptions isteğinde. En iyisi bir UUID. Zorunlu değil; yine de üretim kodunda zorunlu sayın.

curl https://heartotext.com/api/public/v1/transcriptions \
  -H "Authorization: Bearer $H2T_API_KEY" \
  -H "Idempotency-Key: 9f1c2b7a-1f2e-4a0c-9f0b-2c1d3e4f5a6b" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/episode-42.mp3"}'

Tekrarlanan istekler

Aynı anahtarı aynı gövdeyle yeniden gönderdiğinizde saklanmış yanıtı alırsınız: aynı durum, aynı kayıt id’si, üstüne bir de fazladan başlık. İkinci bir kayıt açılmaz, hiçbir şey iki kez faturalanmaz.

Tekrarlanan bir oluşturma isteği

HTTP/1.1 201 Created
Idempotency-Replayed: true

Böylece zaman aşımından, 5xx hatasından ya da kopan bir bağlantıdan sonra hiç düşünmeden yeniden deneyebilirsiniz. Worker’ınızın, ilk denemenin bize ulaşıp ulaşmadığını bilmesine gerek yok.

Çakışmalar

Aynı anahtar, farklı gövde → 409 idempotency_key_reused. Bu neredeyse her zaman, yenisinin üretilmesi gereken yerde eski anahtarın yeniden kullanıldığı anlamına gelir. Hata çağıran taraftadır; hangi kaydı istediğinizi tahmin etmek yerine isteği geri çeviriyoruz.
İlk istek sürerken gelen aynı anahtar → 409 idempotency_request_in_progress. Birkaç saniye bekleyip yeniden sorun. Yavaş bir yükleme sürerken ikinci bir worker aynı işe girişirse karşınıza bu çıkar.

Kapsam ve ömür

Anahtarlar 24 saat boyunca hatırlanır. Sonrasında aynı dize yepyeni bir istektir ve ikinci bir kayıt açar.
Bir idempotency anahtarı tek bir API anahtarına bağlıdır: sizin iki anahtarınız aynı dizeyi kullansa çakışmaz, iki ayrı hesap da çakışmaz.
Bu başlığı yalnızca POST /transcriptions kullanır. Okumalar zaten idempotent; silme isteği de ikinci kez geldiğinde yeni bir şey yapmaz, kaydı bulamayıp 404 döner.

Anahtarı seçmek

Anahtarı işin oluşturulduğu yerde üretin, işle birlikte saklayın ve her denemede aynısını gönderin. Yeniden deneme döngüsünün içinde üretilen anahtar hiçbir şeyi korumaz.
Doğal bir anahtar da olur — podcast-42-episode-7 gibi — yeter ki her kayıt için benzersiz olsun ve altındaki gövdeyi sonradan değiştirmeyin.
En fazla 255 karakter. Daha uzunu 422 döner.