Hear2Text

Sürümler ve kullanımdan kaldırma

v1 içinde haber vermeden neler değişebilir, neler hiç değişmez ve bir şey bozulmadan önce size ne söz veririz.

Sürüm adresin içinde

Bütün endpointler /api/public/v1 altında. Ne sürüm başlığı var ne içerik pazarlığı: hangi adresi çağırdıysanız sözleşmeniz odur. Yaptığımız hiçbir dağıtım sizi sessizce başka bir sürüme taşıyamaz.

Haber vermeden ekleyebileceklerimiz

  • Yanıtta yeni alanlar. İstemciniz tanımadığı alanları görmezden gelmeli.
  • İstekte zorunlu olmayan yeni alanlar.
  • Yeni endpointler ve var olanlara zorunlu olmayan yeni sorgu parametreleri.
  • Açıklayıcı bir alanda yeni değerler — yeni bir progress.step, yeni bir dil kodu, yeni bir failure_reason. Tanımadığınız bir değer geldiğinde hata fırlatmayın; varsayılan davranışa geçin.

v1’de neye güvenebilirsiniz

  • Dört durum. queued, processing, completed, failed — beşincisi yok. Bu dördünü kendi iç iş akışımızdan en baştan bu yüzden ayırdık.
  • Hata zarfı ve katalogdaki her kodun anlamı. Yeni kod eklenebilir; var olan bir kod ne anlam değiştirir ne de ortadan kalkar.
  • Alan adları ve tipleri: belgelenen ne varsa, bir de imleçli sayfalamanın biçimi.
  • Kimlik doğrulama. Bugün oluşturduğunuz anahtar, v1 var olduğu sürece çalışmayı sürdürür.

Hangi değişiklik entegrasyonu bozar

Bir alanı kaldırmak, adını ya da tipini değiştirmek, bir durumun veya bir hata kodunun anlamını kaydırmak, zorunlu olmayan bir istek alanını zorunlu hale getirmek. Bunların hiçbiri v1 içinde yaşanmaz; hepsi /v2 içinde olur: ayrı bir adres, siz hazır olduğunuzda oraya geçersiniz.

Kullanımdan kaldırma ve kapatma

v1 bir gün kapatılırsa yavaş kapatılır ve herkes duyar: duyuruyla kapanış arasında en az on iki ay geçer, anahtarı olan her hesaba e-posta gider ve bu sürenin tamamında her v1 yanıtı iki standart başlık taşır.

Kullanımdan kaldırılmış bir sürümde
Deprecation: Sat, 01 Aug 2026 00:00:00 GMT
Sunset: Mon, 03 Aug 2026 00:00:00 GMT
Link: <https://heartotext.com/api/docs>; rel="deprecation"

Bir yanıtta Deprecation başlığını gördüğünüzde bunu bir uyarı olarak loglayın. Bir geçişin yaklaştığını size en erken haber veren şey budur; üstelik kimsenin artık açmadığı bir gelen kutusuna değil, doğrudan izleme sisteminize düşer.

Esnek bir istemci yazmak

  • Yanıtta tanımadığınız alan varsa ayrıştırmayı hataya düşürmeyin, o alanı atlayın.
  • Tanımadığınız bir status, failure_reason ya da progress.step değerini hata değil, “yeni bir şey” olarak ele alın.
  • Akışınızı error alanına göre dallandırın, message alanına göre asla.
  • Bir cursor ya da id değerini ayrıştırmayın. İkisi de opak, ikisinin de biçimi değişebilir.
  • İstemcinizi OpenAPI belgesinden üretin, arada bir de yeniden üretin: bu sayfalar da kendi testlerimiz de aynı dosyadan çıkıyor.
Sıradaki: Değişiklik günlüğü