Sürüm ve kullanımdan kaldırma
Sürümün yolda taşınması, kırıcı olmayan değişiklikler ve kullanımdan kaldırma süreci.
Geliştirici belgesi
Sürüm yoldadır
Bu belge /api/v1'i anlatır. Sürüm yalnız yolda taşınır; başlıkla ya da sorguyla sürüm seçilmez.
Kırıcı olmayan değişiklikler
Aşağıdakiler v1 içinde, önceden duyurulmadan yapılabilir. İstemciniz bunlara dayanıklı olmalıdır:
- yeni bir uç ya da yöntem,
- yanıta yeni bir alan (tanımadığınız alanı yok sayın),
- yeni, isteğe bağlı bir sorgu süzgeci ya da gövde alanı,
- bir enum'a yeni bir değer (tanımadığınız değeri bilinmeyen olarak ele alın),
- yeni bir olay türü ya da yeni bir hata kodu,
- yeni bir yanıt başlığı.
Her değişiklik makinece denetlenir: depodaki yayımlanmış sözleşme ile yeni OpenAPI belgesi karşılaştırılır ve alan, yol ya da enum değeri kaldıran, yeni zorunlu girdi ekleyen değişiklik yayımlanmaz.
Kırıcı değişiklikler
Bir alanı kaldırmak, türünü ya da anlamını değiştirmek, bir ucu kaldırmak ya da yeni zorunlu girdi eklemek kırıcıdır ve yeni bir sürüm ister (/api/v2). Yeni sürüm yayımlandığında v1 çalışmaya devam eder.
Kullanımdan kaldırma
- Kullanımdan kaldırılan bir uç OpenAPI belgesinde
deprecated: trueile işaretlenir ve Değişiklik günlüğü'ne yazılır. - O ucun her yanıtı
Deprecation(RFC 9745) veSunset(RFC 8594) başlıklarını taşır; varsaLink: <...>; rel="deprecation"geçiş belgesini gösterir. Sunsettarihi, kullanımdan kaldırmanın duyurulmasından en az 12 ay sonradır. Bu tarihe kadar uç olduğu gibi çalışır.
İstemcinizin Deprecation başlığını günlüğe yazmasını öneririz: hangi çağrının taşınması gerektiği böylece kendiliğinden görünür.