Sürümler ve uyumluluk

API’nin tek bir ana sürümü vardır, /v1, ve bu sürüm yalnızca büyür. Bugün yazılan bir entegrasyon, yeni özellikler geldikçe çalışmaya devam eder: dayandığı hiçbir şey yeniden adlandırılmaz, kaldırılmaz ya da yeni bir anlam kazanmaz.

Sürüm numarası

API’nin 1.62.0 gibi bir sürüm numarası vardır. Bu numara her yayında değişir:

• bir şey eklendiğinde ara sürüm numarası: bir uç nokta, bir alan, bir olay;
• bir açıklama ya da ileti metni düzeltildiğinde ve başka hiçbir şey değişmediğinde yama sürümü numarası.

Bir adresin sunduğu sürümü istediğiniz zaman okuyabilirsiniz:

GET /v1/health yanıtında da bir version vardır, ancak bu API’nin sürümü değil, adrese hizmet veren Sursa yayınının sürümüdür.

Ara sürümü siz seçmezsiniz: her isteğe geçerli sürüm yanıt verir. Aşağıdaki kurallar sayesinde bu güvenlidir.

/v1 içinde neler değişebilir

Bu değişiklikler herhangi bir ara sürümde gelebilir. Entegrasyonunuzu bunlardan etkilenmeyecek şekilde yazın:

• Yeni uç noktalar.
• Yeni isteğe bağlı parametreler ve istek alanları. Bunlar olmadan gönderilen istekler önceki gibi davranır.
• Yanıtlarda, nesnelerde ve olaylarda yeni alanlar.
• Yanıtlardaki sabit değer listelerinde yeni değerler: örneğin yeni bir kart durumu ya da yeni bir olay türü.
• Yeni hata kodları ve yeni yanıt başlıkları.
• Daha az katı hâle gelen sınırlar: daha büyük bir en fazla uzunluk, daha geniş bir aralık.
• Hataların yeniden yazılmış message metinleri ve yeniden yazılmış açıklamalar.

Kodunuzun hazırlıklı olması gerekenler

• Bilmediğiniz alanları yok sayın. Bir yanıtta beklediğinizden fazla alan olduğunda hata vermeyin ve bu alanları reddeden katı şemalar kullanmayın.
• Bilmediğiniz enum değerlerini kabul edin. Yanıttaki her sabit değer listesi büyüyebilir. Bilinmeyen bir değeri hata olarak değil, “diğer” olarak ele alın.
• Bilmediğiniz olay türlerini atlayın: hem webhook’larda hem de akışlarda.
• Bilinmeyen hata kodlarını HTTP durumlarına göre ele alın: Hatalar sayfasına bakın.
• JSON nesnelerindeki alanların sırasına bağımlı olmayın, iletilerin tam metnine de.

/v1 içinde hiçbir zaman değişmeyenler

• Bir yol, parametre, alan ya da enum değeri hiçbir zaman yeniden adlandırılmaz ya da kaldırılmaz.
• Bir alanın türü hiçbir zaman değişmez ve bir alan hiçbir zaman yeni bir anlam (örneğin yeni birimler) kazanmaz.
• Bugün kabul edilen bir istek daha sonra reddedilmez.
• Başarılı bir yanıtın durum kodu aynı kalır.
• Hata kodları anlamlarını, hata yanıtlarının detail alanı da biçimini korur.
• Olay türleri hiçbir zaman yeniden adlandırılmaz ya da kaldırılmaz; data nesnelerine yalnızca yeni alanlar eklenir.

Uyumsuz değişiklikler

Bir gün uyumsuz bir değişiklik gerekirse bu değişiklik, /v1 sürümünün yanında /v2 gibi yeni bir ana sürüm olarak yayımlanır. /v1 değişmeden çalışmaya devam eder ve iki sürüm yan yana çalışır.

Bir yol kullanımdan kaldırılacağı zaman:

1. Spesifikasyonda deprecated olarak işaretlenir ve değişiklik günlüğünde kapatılacağı tarihle birlikte listelenir.
2. Yanıtları Deprecation: true ve Sunset: <date> başlıklarını taşır.
3. Duyurudan sonra en az 180 gün çalışmaya devam eder. API anahtarları bu yolu kullanan kuruluşlara en az 90 gün önceden yazılı olarak bildirilir.
4. Kullanım sonu tarihinden sonra 90 gün daha api.gone koduyla 410 yanıtı verir.

Günlüklerinizde ya da izleme araçlarınızda Deprecation başlığını takip edin: bu başlık, kullandığınız bir yolun kaldırılacağının en erken işaretidir.

Haberdar kalma

Bu portalın değişiklik günlüğü her yayını, nelerin eklendiği ve nelerin kullanım dışı bırakıldığıyla birlikte listeler. Kendi entegrasyonunuzu yükseltmeden önce kodunu, entegrasyonu geliştirirken temel aldığınız sürümden bu yana eklenen kayıtlarla karşılaştırın.