Sürümleme

Yürürlükteki sürüm API v1. Tek bir söz veriyoruz: çalışan entegrasyonunuzu sessizce kırmayız. Bunun pratik karşılığı, neyin değişebileceğini ve neyin değişemeyeceğini önceden bilmenizdir.

Değişmeyecek olanlar

• Olay adı. order.ready her zaman order.ready kalır. Abonelik listenizdeki ve X-Veni-Event başlığındaki değer budur.
• Alanların anlamı. Var olan bir alan aynı şeyi ifade etmeye devam eder.
• Teslimat kimliğinin davranışı. X-Veni-Delivery yeniden denemelerde aynı kalır.
• İmza hesabı. v1 ve v2 formülleri sabittir.

Haber vermeden değişebilecek olanlar

• Gövdeye yeni alan eklenmesi. Tanımadığınız alanı yok sayın; bu kırıcı bir değişiklik sayılmaz.
• Katalogda yeni olay. Abone olmadığınız bir olay size gönderilmez.
• Yeni isteğe bağlı istek alanı. Göndermezseniz davranış değişmez.

Bu yüzden ayrıştırıcınız katı olmamalı: bilinmeyen alanda hata veren bir JSON çözücü ilk ekleme gününde kırılır.

Kırıcı değişiklik olursa

Bir alanın kaldırılması ya da anlamının değişmesi gerekirse yeni bir sürüm çıkarılır. CloudEvents tipindeki son parça bunu taşır:

tr.com.veni.restaurant.order.ready.v1
                                  └── payload sürümü

Yeni sürüm …v2 olarak gelir. Kısa ad (order.ready) aynı kalır; iki sürüm bir süre birlikte yayınlanır ve siz hazır olduğunuzda geçersiniz.

Uç adresleri

Uç yolları /api/v1/… ile sürümlenir. v1 içinde kırıcı değişiklik yapılmaz; gerekirse v2 yolu açılır ve v1 bir süre birlikte yaşar.

İmza sürümü

Tek imza şeması vardır: X-Veni-Signature başlığında v1,<hex>. İmza zaman damgasını kapsar, yani tekrar oynatmayı ayıklayabilirsiniz. Ayrıntı: Webhook imzası.

Şema değişirse değer ön eki (v1,) değişir ve yeni ön ek bir süre eskisiyle birlikte gönderilir; doğrulayıcınız başlığı boşluktan böldüğü ve herhangi biri tutuyorsa kabul ettiği için geçiş kesintisiz olur.

Değişiklikleri izlemek

Sözleşmeyi etkileyen her değişiklik Değişiklikler sayfasına tarihiyle yazılır.

Dayanıklı alıcı listesi

• Bilinmeyen JSON alanını yok sayın.
• Bilinmediğiniz bir olay adı gelirse 200 dönüp atlayın; hata vermeyin.
• Tutarları metin olarak okuyun ("149.90"), kayan noktaya çevirirken kendi para tipinizi kullanın.
• Tarihleri RFC3339 olarak çözün; saat dilimini kendiniz varsaymayın.
• Yeni bir alana bağımlı iş mantığı yazmadan önce o alanın her olayda geldiğinden emin olun; isteğe bağlı alanlar omitempty ile gelmeyebilir.