ASP.NET Core Web Api ve Versiyonlama
Merhaba,
Uygulamalarımızın üretim ortamlarında çalışırken kontrolleri aslında genel olarak zor işlemler içeriyor. Tabii, bu işlemleri kolaylaştırmak için günümüzde önemli çözümler mevcut. Fakat en temel yaşadığımız sorunların başında yeni özelliklerin üretim ortamlarında devreye alınması gelmekte.
Aslında buraya kadar bir problem yok. Tamam, yeni özellikleri geliştir ve üretim ortamına al. Peki bu servisleri kullanan uygulamalar? Onların bu yaptığımıza tepkisi ne olur acaba? Büyük ihtimalle eğer ciddi değişiklikleri üretim ortamına çıkıyorsak hatalar alınacak ve projemiz belirli bir süre çalışmayacaktır. Böyle bir durumu da kimse istemez diye düşünüyorum.
Fakat, mevcut kullanıcıların bundan etkilenmemesini sağlamak tabii ki mümkün. Bu konuda kullanılan farklı çözümler ve yöntemler mevcut. Seçimin kişi, ekip, ekibin bilgisi ve tecrübesi ile doğru orantılı olduğunu düşünüyorum.
- Farklı bir metot olarak üretim ortamına alalım ? (Gerçekten mi? API’yi kullanan uygulamalara ne diyelim?)
- Bir parametreye bağlayabiliriz belki ?( Mevcut metodun kodlarında değişiklik mi? Ee test ihtiyacı? Hata olasılığı?)
- Özellik açma / kapama (Feature Toggling) yapabiliriz? (Evet belki olabilir fakat parametre gibi olmayacak mı bir nevi ? Farklı uygulamalar mevcut denenebilir.)
- Peki, versiyonlama yapsak ?
Versiyonlama, evet bugün bu konu hakkına bir şeyler yazmak istedim. ASP.NET Core Web API üzerinde versiyonlamayı nasıl yapabiliriz? Hangi yöntemler ile bu versiyonlama işlemlerini kullanabiliriz?
O zaman beraber ASP.NET Core Web API üzerinde versiyonlama işlemlerini nasıl yapıyoruz? Bakalım.
Önce yeni bir Web API projesi oluşturalım.
Visual Studio Code uygulamamızdan yeni bir terminal başlattıktan sonra aşağıdaki komut ile yeni WebApi projemizi oluşturalım.
Versiyonlama işlemlerimizi yapabilmek için bir Nuget paketine ihtiyacımız olacaktır. Aşağıdaki komut ile Microsoft.AspNetCore.Mvc.Versioning paketini projemize ekleyelim.
Paket kurulumundan sonra Startup.cs sınıfımızda aşağıda bulunan konfigurasyon tanımlarını yapmamız gerekmektedir.
Şimdi versiyonlama işlemlerimizi yapabiliriz.
Versiyonlama işlemleri birkaç yöntem ile yapılabilmektedir. Bu versiyonlama tekniklerini sırasıyla kontrol edelim.
API metodlarımızı değişikliğimizden sonra çağırdığımızda Header bilgileri içerisinde kullanılabilecek versiyon bilgilerini görüntüleme imkanına sahip oluyoruz.
URL Sorgusuna Dayalı Sürüm Oluşturma (URL Query Based Versioning)
Kullanılan URL adresi üzerinden versiyon bilgisi alınarak versiyonlama işlemleri yapılır. Aşağıda bulunan iki controller aynı API adresi üzerinden gelinen versiyon bilgisine göre çalışacaktır.
Göreceğimiz gibi burada farklı isimler ile tanımlanmış iki adet controller bulunmaktadır. Burada belirtilen route bilgileri ise aynıdır. API adresi olarak çağırdığımız api/home adresi bu farklılaştırmayı ApiVersion özelliği ile yapmaktadır. API adresine gönderilen query string bilgisi ile versiyon ayırımı yapılabilmektedir. Aşağıda iki versiyon için Postman üzerinden çağırım örneklerini bulabilirsiniz.
http://localhost:5000/api/home?api-version=2.0
Eğer API adresimizi bir versiyon bilgisi göndermeden çalıştırırsak o zaman varsayılan olarak 1.0 versiyonu gelecektir.
URL Yoluna Dayalı Sürüm Oluşturma (URL Path Based Versioning)
Genel yaygın kullanımlardan biri olan URL path kullanımı hem client uygulamaları için kullanımı kolay bir yöntemdir.
Postman üzerinden versiyon bazlı çağırımlarımız ise aşağıdaki gibi olacaktır.
Http Başlık Tabanlı Sürüm Oluşturma (Http Header Based Versioning)
Görüldüğü gibi her versiyonlama yöntemi biraz daha kullanım bakımından daha iyi hale gelerek devam etmektedir. Tabii bu yöntemlerin client uygulama veya kullanılan yapıya uygun şekilde seçilmesi önemlidir. HTTP Header üzerinden versiyonlama kullanma yöntemi client uygulama tarafından gönderilen header bilgisi üzerinden versiyon bilgisini alarak çalışmaktadır.
Header üzerinden versiyon bilgisinin alınabilmesi için yapılandırmada ufak bir değişiklik yapmamız gerekecek. Bunun için Startup.cs sınıfımıza aşağıdaki kod satırını eklememiz gerekmektedir.
Kod değişikliğimiz ile API uygulamamızın versiyon bilgisini header üzerinden almasını sağlamış olduk.
Şimdi, Postman üzerinden header bilgisi olarak versiyon bilgimizi geçebilir ve sonuçları görebiliriz.
Tek Controller Birden Fazla Action
Bazı durumlarda tek bir controller içerisinde bulunan action bilgilerinin de versiyonlanmasını isteyebiliriz. Böyle bir durumda controller içinde bulunan action metoduna MapToApiVersiyon özellik geçişini yapmamız yeterli olacaktır.
Header üzerinden alınan versiyon bilgisi ile yeni metodumuzun çalışması aşağıdaki gibi olacaktır.
API Versiyonlarını Kullanımdan Kaldırmak
API için hazırlanmış eski versiyonların kullanımdan kaldırılmasını (Deprecated) yine sınıf özelliği tanımları ile yapma imkanına sahibiz. Böyle bir durumda metodlarımızı API üzerinden çağırdığımızda kullanılmayan versiyon bilgilerine ulaşabiliriz.
Postman üzerinden metodumuzu çağırdığımız zaman ise Header alanında versiyonlar ile ilgili bilgileri görebiliriz.
Versiyon Tanımlarını Oluşturmak
Versiyon tanımlarının şimdiye kadar Controller veya Action bilgileri üzerinden tanımladık. Servis tanımlarını yaparken Controller versiyonlarının tanımlanmasını da sağlayabiliriz.
Eklediğimiz kod bloğunda hangi controller hangi versiyona sahip olacak bilgilerini tanımlayabiliyoruz. Controller bilgilerimiz ise aşağıdaki gibi olacaktır.
İstenilen API Versiyonunu Görüntüleyebilmek
Peki, böyle bir yapı içerisinde gelinen API versiyonunu nasıl alacağız? Versiyon bilgisini alarak istenilen durumlarda gelinen versiyon için de ayrı işlemler yapabiliriz. Bunun için GetRequestedApiVersion() metodundan yararlanabiliriz.
Postman çağırımlarımız ile metodların verdikleri cevaplar da aşağıdaki gibi olacaktır.
Bu yazımda API üzerinde nasıl versiyonlama yapabileceğimizi ve bu versiyonları nasıl yönetebileceğimizi biraz hem kendim anlamaya hem de sizlere açıklamaya çalıştım.
Versiyonlama yöntemleri birden fazla olduğundan dolayı ihtiyacımızı karşılayan uygun yöntem uygulamamızın yapısı, client kullanımları ve API kullanan diğer uygulamaların durumlarından dolayı farklılık gösterecektir.
Bir başka yazıda görüşmek üzere…
