asp.net-core-web-api-versioning-prosesi

ASP.NET CORE WEB API versioning prosesi

Web API hazırlayan zaman versiya məsələsinə xüsusi diqqət yetirmək lazımdır. Çünki APİ-ni serverə publish etdikdən sonra artıq o bir növ sərtləşmiş bir interfeysə çevrilir və bir neçə klient tərəfindən istifadə edildiyinə görə APİ interfeysini çox rahatlıqla dəyişmək mümkün olmur.

           Hansı hallarda APİ versiyalama(APİ versioning) istifadə etmək lazımdır?

 1)Tələblər dəyişdikcə dəyişikliyə ayaq uydurmaq, bununla belə, könhə interfeysi mümkün qədər zədələməmək,müşayiət etmək lazımdırsa.

2)Yeni və köhnə interfeys istifadəçilərini support etmək lazımdırsa

3)Yeni tələblərə uyğun köhnə interfeysi modifikasiya etmədən yeni tələb olunan funksionallığı dəstəkləmək lazımdırsa

4)Köklü dəyişiklikdə könhə interfeys istifadəçilərini kontraktı qırmadan yeni funksionallığa integrasiya etmək lazımdırsa

 APİ versiyalaması prosesi müxtəlif formatlarda həyata keçirilir:


1)   URL vasitəsilə


a)    api/v2/orders

b)   api/orders?v=2.0


   2)Header vasitəsilə


      a)x-version: 2.0

      b)accept: application/json;version:2.0

     c)content-type:application/vnd.myapp.comp.v1+json

    d)accept: application/vnd.myapp.comp.v1+json

 

Asp.NET CORE 3.x-da versiyalanmanı təmin etmək üçün ilk öncə proyektə nuget üzərindən Versioning.dll-ni yükləmək lazımdır.

Install-package Microsoft.aspnetcore.mvc.Versioning

Yüklənmə bitdikdən sonra Startup faylında ConfigureServices() metoduna Versioning servisini əlavə etmək lazımdır

  public void ConfigureServices(IServiceCollection services)
        {
           
            services.AddControllers();
            services.AddApiVersioning();
        }

Nümunə üçün standard kontrolleri( burada WeatherForecastController)  saxlayırıq. Servisini əlavə etdikdən sonra servisi F5 ilə işə salırıq və belə bir yazı ilə rastlaşırıq.

Səbəb odur ki, sadəcə servisi qoşmaq kifayət etmir. Mütləq şəkildə ən azı hər bir kontrollerə , hansı APİ version-da olduğunu göstərmək lazımdır.

 [ApiController]
    [Route("[controller]")]
    [ApiVersion("1.0")]
    public class WeatherForecastController : ControllerBase
    {

 ApiVersion atributu kontrollerə tətbiq olunduqda kontrollerdəki bütün əməliyyatların göstərilən versiyaya aid olduğunu bildirir. Bizim nümunədə isə Kontroller artıq 1.0 versiyasına malikdir. Amma proyekti build edib işə saldıqda ilk şəkildəki error ilə rastlaşırıq. Səbəb odur ki, kontrollerə versiyanı göstərsək belə, ümumi APi-yə, ondan hansı versiyanı tələb etdiyimizi göstərməmişik. Bununçün soruğunu aşağıdakı kimi vermək lazımdır

Url sətrində versiyaya aid heç bir şey göstərilmədən default olaraq 1.0 versiyasının yüklənməsini istəyiriksə ozaman Servisdə əlavə konfig aparmaq lazımdır. Beləki

 public void ConfigureServices(IServiceCollection services)
        {
           
            services.AddControllers();
            services.AddApiVersioning(x=>
            {
                //heç bir versiya göstərilmədikdə default versiyanı göstər
                x.AssumeDefaultVersionWhenUnspecified = true;
               
                //default olaraq 1.0 versiyasıdır
                x.DefaultApiVersion = new ApiVersion(1, 0);
            });
        }


           Klient sorğu verən zaman hansı api versiyalarının dəstəkləndiyini Header-lər vasitəsilə ona göndərmək olur. Bununçün ReportApiVersions property-sindən istifadə edirik.

   services.AddApiVersioning(x=>
            {
                //hansı api versiyalarının dəstəkləndiyini bildir
                x.ReportApiVersions = true;
                //heç bir versiya göstərilmədikdə default versiyanı göstər
                x.AssumeDefaultVersionWhenUnspecified = true;
               
                //default olaraq 1.0 versiyasıdır
                x.DefaultApiVersion = new ApiVersion(1, 0);
            });

Sorğu verdikdən sonra geriyə belə bir cavab alırıq

Kontrollerin bir neçə api versiyasını dəstəkləməsi üçün sadəcə eyni atributu bir neçə dəfə müxtəlif versiyalarla tətbiq etmək kifayətdir

 [ApiController]
    [Route("[controller]")]
    [ApiVersion("1.0")]
    [ApiVersion("1.1")]
    public class WeatherForecastController : ControllerBase
    {

Yuxarıdakı kod hesabına artıq kontrollerimiz 1.1 versiyasını da dəstəkləyir.

Belə olan halda aşağıdakı action bütün növ api versiyaları üçün işləyəcək

 [HttpGet]
        public IEnumerable WorkForAllVersions()
        {
            var rng = new Random();
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = rng.Next(-20, 55),
                Summary = Summaries[rng.Next(Summaries.Length)]
            })
            .ToArray();
        }

Əgər ki, hansısa bir action-nın yalnızca konkret bir APİ versiyası üçün çağrılmasını istəyiriksə ozaman MapToApiVersion adlanan atributdan istifadə edəcəyik

 //action yalnızca api 1.1 versiyası üçün çağrıla bilir
        //qalan api versiyaları üçün WorkForAllVersions() action-ı çağrılacaq
        [MapToApiVersion("1.1")]
        public ActionResultstring>> GetResponse()
        {
            return Summaries.Where(x => x.StartsWith("C")).ToList();
        }


 AssumeDefaultVersionWhenUnspecified funksionallığını deaktiv etdikdə artıq URL üzərindən api-version açar sözünü yazmadan APİ versiyasını dəyişmək olmur. Amma bununla belə, həmin açar sözü başqa bir sözlə əvəzləmək istəsək sadəcə aşağıdakı kodu əlavə etməyimiz kifayətdir.

 services.AddApiVersioning(x=>
            {
                //artıq bundan sonra ?ver=1.x yazmaqla APİ-ni çağıra biləcəyik
                x.ApiVersionReader = new QueryStringApiVersionReader("ver");

                //hansı api versiyalarının dəstəkləndiyini bildir
                x.ReportApiVersions = true;
                //heç bir versiya göstərilmədikdə default versiyanı göstər
               // x.AssumeDefaultVersionWhenUnspecified = true;
               
                //default olaraq 1.0 versiyasıdır
                x.DefaultApiVersion = new ApiVersion(1, 0);
            });

Artıq url üzərindən ?api-version yox, sadəcə ?ver=x.x yazmaqla istənilən dəstəklənən versiyanı çağırmaq olur

Tural

Tural Süleymani

Süleymani Tural Microsoft-un MCSD statuslu mütəxəssisidir, 2008-ci ildən bu yana proqramlaşdırma üzrə tədris aparır

Müəllifin bu dildə ən son postları

Bu yazıları da bəyənə bilərsiniz