API Versiyonlama: Mevcut İstemcileri Bozmadan API'yi Geliştirmek

Bir API'yi mobil uygulama, iş ortakları veya başka sistemler kullanmaya başladığında, yapılan her değişiklik onları etkileyebilir. Bir alanın adını değiştirmek bile, güncellenmemiş bir mobil uygulamanın çökmesine yol açabilir. API versiyonlama, API'yi geliştirmeye devam ederken mevcut istemcileri korumanın yoludur.

Kırıcı ve kırıcı olmayan değişiklikler

Kırıcı değişiklikler:

Bir alanı kaldırmak veya adını değiştirmek
Alan türünü değiştirmek (sayıdan metne)
Zorunlu yeni bir parametre eklemek
Hata kodlarının anlamını değiştirmek

Genellikle kırıcı olmayanlar:

Yanıta yeni, isteğe bağlı bir alan eklemek
Yeni bir uç nokta eklemek
İsteğe bağlı yeni bir parametre eklemek

Kırıcı olmayan değişiklikler için yeni sürüm gerekmez; istemcilerin bilinmeyen alanları yok sayacak şekilde yazılması önerilir.

Versiyonlama yöntemleri

Adreste: /api/v1/siparisler, /api/v2/siparisler. En görünür ve anlaşılır yöntem.
Sorgu parametresinde: /api/siparisler?api-version=2.0.
HTTP başlığında: X-Api-Version: 2. Adresleri temiz tutar ama görünürlüğü düşüktür.
Medya türünde: Accept başlığında sürüm belirtilir.

Önemli olan bir yöntemi seçip tutarlı şekilde uygulamaktır.

Eski sürümleri emekliye ayırmak

Eski sürümün ne zaman kapatılacağını önceden duyurun.
Yanıtlarda kullanımdan kaldırma bilgisi veren başlıklar ekleyin.
Hangi istemcilerin eski sürümü kullandığını loglardan izleyin. Bkz. .NET'te loglama.
Geçiş için yeterli süre ve belge sağlayın.

Belgeleme

Her sürümün ayrı ve güncel belgesi olmalıdır. OpenAPI ile her sürüm için ayrı doküman üretmek mümkündür. Bkz. OpenAPI ve Swagger.

.NET'te uygulama

ASP.NET Core için yaygın kullanılan açık kaynaklı Asp.Versioning paketleri, adres, sorgu ve başlık tabanlı versiyonlamayı ve sürüm bazlı belge üretimini destekler.

Webhook ve olaylarda da sürüm

API'niz webhook gönderiyorsa, olay yüklerinin yapısı da sürümlenmelidir.

Sık sorulan sorular

Her değişiklikte yeni sürüm mü açmalıyım?

Hayır. Yalnızca kırıcı değişiklikler yeni sürüm gerektirir. Çok sayıda sürümü aynı anda yaşatmak bakım yükünü artırır.

Yalnızca kendi ön yüzümüz kullanıyorsa versiyonlama gerekir mi?

Web ön yüzü ve API birlikte yayımlanıyorsa çoğu zaman gerekmez. Mobil uygulama veya dış istemciler varsa gereklidir.

Sonuç

Versiyonlama, API'nin güvenilir bir sözleşme olmasını sağlar. API tasarımı ve entegrasyonları için destek alabilirsiniz.