Sürümleme

Sürüm yoldadır

Her rota /api/integrations/v1 altındadır. Çalışan bir entegrasyonu bozabilecek bir değişiklik v1’e asla yapılmaz: yeni bir sürüme (/v2) girer ve bu sürüm aşağıdaki bildirim süresi boyunca v1’in yanında çalışır.

v1 içinde neler değişebilir

Bu değişiklikler bildirimsiz yapılır; entegrasyonunuzu onları kabul edecek şekilde kurun:

• Yeni uç noktalar.
• Yeni isteğe bağlı istek alanları ve sorgu parametreleri.
• Yanıtlarda, hata gövdelerinde ve webhook data alanında yeni alanlar.
• Durum ya da tür listeleyen alanlarda yeni değerler (örneğin yeni bir status, milestoneType ya da belge category değeri) ve yeni hata kodları.
• Yeni webhook olay türleri (abonelik yalnız seçtiği türleri alır).
• OpenAPI belgesinde daha açık açıklamalar.

Uygulamada: bilmediğiniz alanları yok sayın, bilmediğiniz bir değeri “diğer” sayın, bilmediğiniz bir hata kodunu HTTP durumuna göre ele alın.

Neler kırıcıdır

• Bir uç noktayı, alanı, olay türünü ya da değeri kaldırmak veya yeniden adlandırmak.
• Bir alanın türünü ya da anlamını değiştirmek, isteğe bağlı bir istek alanını zorunlu yapmak.
• Kimlik doğrulamayı, imza yöntemini ya da hata biçimini değiştirmek.

Bildirim

Kırıcı bir değişiklik ve bir sürümün sonu en az 6 ay önceden duyurulur:

• etkin entegrasyonu olan her şirketin Sahip ve Yöneticilerine e-postayla;
• değişiklik günlüğünde;
• etkilenen rotalarda, duyurudan itibaren bir Deprecation başlığıyla (RFC 9745) ve rotanın duracağı tarihi veren bir Sunset başlığıyla (RFC 8594).

Tek istisna güvenlik düzeltmeleridir: müşteri verisini korumak için gereken bir değişiklik daha önce yapılabilir ve mümkün olan en erken zamanda duyurulur.