AspNetCore Api Versiyonlama, Api Versioning Nedir?
Backend yazılımcıları olarak bir çoğumuz başkalarının tükettiği API’ler yazmışızdır veya projemize başka projeler ile entegrasyon yapacağımız zaman bize çağırmamız için verilen adreslerin içerisinde versiyon numaralarını fark etmişizdir.
https://baseUrl/api/v1/…… şeklinde bir URL bilgisinin içerisindeki v1 kısmı bizim için çağırdığımız metodun versiyon numarası oluyor. Peki bu versiyon numaralarını neden kullanıyoruz ki? Ne faydası var bize?
Versiyonlandırma genelde projeyi yazıyorken en başlarda ihtiyacımız olan bir şey olmuyor ancak geleceği görebiliyorsak projenin başında eklemeye gayret edebiliriz. Diyelim ki sipariş listesini geriye döndüğünüz bir metodunuz var API’nizde. Aradan günler, haftalar, aylar geçti ve bu metodunuzda bir değişiklik yapmanız gerekecek. Öyle bir değişiklik ki bu, sizin metodunuzu kullanan “CLIENT” uygulamaların hata almasına sebep olabilir. Metodunuzdan geriye döndüğünüz objenin bir alanını değiştirmiş hatta silmiş olabilirsiniz. Bu durumda sizin “CLIENT”larınızın da değişiklik yapması gerekecektir. Peki bu değişikliği tüm CLIENT’larınıza aynı anda yaptırabilir misiniz? Büyük ihtimalle yaptıramazsınız.
İşte tam bu noktada .NET dünyasındaki ApiVersioning API’si hayatımızda önemli bir rol oynamaya başlıyor. ApiVersioning’deki temel mantık, aynı metodu farklı bir versiyon ile çağırmayı sağlamaktır. Dolayısı ile hem eski veresiyonu hem de yeni versiyonu aynı anda yayında olabilir. Yaptığınız değişiklik aktif olarak metodunuzu kullanan CLIENT’ları etkilemeyecek, ve onlar da yeni metodu kullanmak isterse bunu engellemeyecektir.
NET5 içerisinde bir WebAPI projesi geliştiriyorsanız eğer startup.cs içerisinde ConfigureServices metodunun içerisinde services.AddApiVersioning(); metodunu çağırmanız ve bunu sisteme eklemeniz gerekecek. Bu metodu çağırdıktan sonra artık API’niz verisyonlamayı destekleyecektir ama bu kadarla bırakamayız. Çünkü bu satırı ekledikten sonra metodlarınız hata vermeye başlayacaktır. Çünkü sistemimizi doğru bir şekilde ayarlamadık henüz. Doğru şekilde ayarlayabilmek için ise aşağıdaki şekilde değiştirebiliriz metodumuzu. Bu API’leri kullanabilmek için şu paketi projeye eklemek gerekiyor. Nuget --> Microsoft.AspNetCore.Mvc.Versioning
Yukarıdaki kodlar şöyle bir inceleyelim. DefaultApiVersion kısmı bizim için hayli önemli. Metodlarımızı çağıran CLIENT’lar herhangi bir versiyon bilgisi göndermediklerinde, varsayılan olarak 1.0 versiyonu kullanılsın diyoruz. Bir altındaki satır ise daha önemli :) Eğer versiyon bilgisi göndermezlerse, sistemimiz hata vermeden çalışmaya devam etsin ve varsayılan olarak da 1.0 versiyonu gönderilmiş gibi davransın. Onun altındaki satır, API’lerimizi tüketen CLIENT uygulamalarına Response Header kısmında bir bilgi dönmemizi sağlıyor. Bu bilgi ise, bu metod için hangi API Versiyonlarının kullanılabileceğini içeriyor. Bir metodun birden fazla api versiyonu ile çalışabileceğini unutmayalım. En son satırda ApiVersionReader parametresini dolduruyoruz. Burası bizim için, CLIENT uygulamalara bana versiyon belirtmek isterse bunu hangi yol ile yapacaklar onu belirttiğimiz alan. Birden fazla yöntemi aynı anda bu şekilde kullanabiliriz. UrlSegmentApiVersionReader ile kullanıcılar tıpkı yukarıda belirttiğim gibi ../api/v1/… şekilde tanımlama yapabilsin diye. HeaderApiVersionReader kısmı ise, benim metoduma istek yapılırken request header kısmında x-api-version şeklinde bir değişken gönderirlerse onu da kabul ederim diyebilmek için. MediaTypeApiVersionReader kısmı ise yine header da zaten gönderilen Content-Type veya Accept parametresinin içerisinde de x-api-version değerini gönderirsen onu kabul ederim demek için. aşağıda 3 örnek kullanımı mevcut.
URL -> https://baseurl/api/v1/metod
Header -> x-api-version:1.0
MediaType -> Accept/Content-Type: application/json; x-api-version=1.0
Buradaki şekilde versiyon bilgisi aldığımıza göre, controller’larımızı ve hatta Action’larımızı da buna göre şekillendirebiliriz isterseniz. Zorunlu değil ama. Eğer Controller’larımızda URL den gelen bilgiyi de almak istersek aşağıdaki biri bir attribute eklememiz gerekecek. ApiVersion attribute’ü ile bu Controller sadece v1.0 versiyonunu kabul eder diye belirmiş olduk. Aynı Controller birden fazla versiyon kabul edebileceği için, ApiVersion attribute’ünü iki kez kullanabilir ve versiyonlarını içerisine parametre olarak yazabiliriz. Route içerisinde de artık v ile başlayan bir versiyon numarasını kabul edeceğimizi belirtmiş oluyoruz.
Aynı Controller içerisinde birden fazla metodumuz var ama bu metodların da versiyon numaralarına sahip olmasını istersek şöyle yapabiliriz.
Yukarıdaki OrderController içerisindeki GetOrdersv2 metodu hariç tüm metodlar version 1.0 ile çalışmaktayken GetOrdersv2 metodu versiyon 2.0 ile çalışmaktadır. Dolayısı ile aynı Controller içerisindeki metodlarımızı bu şekilde versiyonlayabiliriz. Ama buradaki “Best Practice” Controllers klasörü altında versiyon numaralarına göre ayrı klasörler açarak ayrı Controller’lar kullanmaktır. Aşağıda bir örneğini görebiliriniz.
Bu durumda Controller’larımız aşağıdaki gibi olacaktır.
Bu yapılan değişikliklerin Swagger üzerinde gösterilmesi durumunu da yine AspNet Core içerisindeki Swagger API’larını kullanarak düzenleyebiliriz. Aşağıdaki github repomda bu projeyi bulabilirsiniz. Youtube’daki kanalımda ise projeyi sıfırdan yaptığım videoyu izleyebilirsiniz.
Github Repo: https://github.com/salihcantekin/youtube_ApiVersioning
Youtube Video: https://www.youtube.com/watch?v=Iu5OnVJxCnA
İyi okumalar, iyi seyirler. Bir sonraki makalede görüşmek üzere.
