Kako koristiti API izradu verzija u ASP.NET Coreu

Kada razvijate API-je, trebali biste imati na umu jedno: promjene su neizbježne. Kada vaš API dosegne točku u kojoj trebate dodati više odgovornosti, trebali biste razmotriti verziju API-ja. Stoga će vam trebati strategija izrade verzija.

Postoji nekoliko pristupa API-jevima za izradu verzija i svaki od njih ima svoje prednosti i nedostatke. U ovom će se članku raspravljati o izazovima API-ja za verziranje i kako možete raditi s Microsoftovim paketom ASP.NET Core MVC Versioning za verziju RESTful API-ja ugrađenih u ASP.NET Core. Više o verzijama web API-ja možete pročitati u mom prethodnom članku ovdje. 

Stvorite ASP.NET Core 3.1 API projekt

Prvo, kreirajmo ASP.NET Core projekt u Visual Studiju. Pod pretpostavkom da je Visual Studio 2019 instaliran u vašem sustavu, slijedite korake opisane u nastavku da biste u Visual Studiou stvorili novi ASP.NET Core projekt.

  1. Pokrenite Visual Studio IDE.
  2. Kliknite "Stvori novi projekt".
  3. U prozoru "Stvori novi projekt" s popisa predložaka odaberite "ASP.NET Core Web Application".
  4. Kliknite Dalje.
  5. U sljedećem prozoru "Konfiguriranje novog projekta" navedite naziv i mjesto za novi projekt.
  6. Kliknite Stvori.
  7. U prozoru "Stvori novu web-aplikaciju ASP.NET Core" odaberite .NET Core kao vrijeme izvođenja i ASP.NET Core 3.1 (ili noviju) s padajućeg popisa na vrhu. Ovdje ću koristiti ASP.NET Core 3.1.
  8. Odaberite "API" kao predložak projekta da biste stvorili novu aplikaciju ASP.NET Core API. 
  9. Obavezno označite potvrdne okvire "Omogući podršku za Docker" i "Konfiguriraj za HTTPS" jer ovdje nećemo koristiti te značajke.
  10. Provjerite je li provjera autentičnosti postavljena na "Bez provjere autentičnosti" jer ni mi nećemo koristiti provjeru autentičnosti.
  11. Kliknite Stvori. 

To će stvoriti novi ASP.NET Core API projekt u Visual Studiju. Odaberite mapu rješenja Controllers u prozoru Solution Explorer i kliknite "Dodaj -> Controller ..." da biste stvorili novi kontroler nazvan DefaultController.

Zamijenite izvorni kod klase DefaultController sljedećim kodom.

    [Ruta ("api / [kontroler]")]

    [ApiController]

    javna klasa DefaultController: ControllerBase

    {

        niz [] autori = novi niz []

        {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

        [HttpGet]

        javni IEnumerable Get ()

        {

            povratak autora;

        }

    }

Ovaj ćemo upravljač koristiti u sljedećim odjeljcima ovog članka.

Da biste implementirali API izdanje verzija u ASP.NET Core, morate učiniti sljedeće:

  1. Instalirajte ASP.NET Core MVC paket za inačice verzija.
  2. Konfigurirajte izradu API-ja u klasi Startup.
  3. Označite kontrolere i radnje odgovarajućim atributima.

Instalirajte ASP.NET Core MVC paket za inačice verzija

ASP.NET Core pruža podršku za izradu verzija API-ja odmah. Da biste iskoristili verzije API-ja, sve što trebate je instalirati paket Microsoft.AspNetCore.Mvc.Versioning iz tvrtke NuGet. To možete učiniti putem upravitelja paketa NuGet unutar IDE-a Visual Studio 2019 ili izvršavanjem sljedeće naredbe na konzoli upravitelja paketa NuGet:

Instalacijski paket Microsoft.AspNetCore.Mvc.Versioning

Imajte na umu da ako koristite ASP.NET Web API, trebali biste dodati paket Microsoft.AspNet.WebApi.Versioning.

Konfigurirajte izradu verzija API-ja u ASP.NET Core

Sada kada je u vaš projekt instaliran potreban paket za verziranje vašeg API-ja, možete konfigurirati API-je za verziranje u metodi ConfigureServices klase Startup. Sljedeći isječak koda ilustrira kako se to može postići.

javna praznina ConfigureServices (usluge IServiceCollection)

{

  services.AddControllers ();

  usluge.AddApiVersioning ();

}

Kada uputite zahtjev za dobivanje API-ja, prikazat će se pogreška prikazana na slici 1.

Da biste riješili ovu pogrešku, možete odrediti zadanu verziju prilikom dodavanja usluga za izradu API-ja u spremnik. Možda ćete htjeti koristiti i zadanu verziju ako verzija nije navedena u zahtjevu. Sljedeći isječak koda pokazuje kako možete postaviti zadanu verziju kao 1.0 pomoću svojstva AssumeDefaultVersionWhenUnspecified ako podaci o verziji nisu dostupni u zahtjevu.

usluge.AddApiVersioning (config =>

{

   config.DefaultApiVersion = novi ApiVersion (1, 0);

   config.AssumeDefaultVersionWhenUnspecified = true;

});

Imajte na umu kako se glavna verzija i mala verzija prosljeđuju konstruktoru klase ApiVersion u vrijeme dodjele zadane verzije. Svojstvo AssumeDefaultVersionWhenUnspecified može sadržavati istinite ili lažne vrijednosti. Ako je to točno, koristit će se zadana verzija navedena prilikom konfiguriranja API-ja za izradu verzija, ako nisu dostupne informacije o verziji.

Kompletni izvorni kod metode ConfigureServices dat je u nastavku za vašu referencu.

javna praznina ConfigureServices (usluge IServiceCollection)

{

    services.AddControllers ();

    usluge.AddApiVersioning (config =>

    {

         config.DefaultApiVersion = novi ApiVersion (1, 0);

         config.AssumeDefaultVersionWhenUnspecified = true;

    });

}

Budući da niste naveli nijednu informaciju o verziji, sve krajnje točke imat će zadanu verziju 1.0.

Prijavite sve podržane verzije vašeg API-ja

Možda ćete htjeti obavijestiti klijente API-ja o svim podržanim verzijama. Da biste to učinili, trebali biste iskoristiti svojstvo ReportApiVersions kao što je prikazano u donjem isječku koda.

usluge.AddApiVersioning (config =>

{

  config.DefaultApiVersion = novi ApiVersion (1, 0);

  config.AssumeDefaultVersionWhenUnspecified = true;

  config.ReportApiVersions = true;

});

Koristite verzije u kontroloru i metode djelovanja

Sada dodajmo nekoliko podržanih verzija na naš kontroler pomoću atributa kao što je prikazano u isječku koda koji je dan u nastavku.

    [Ruta ("api / [kontroler]")]

    [ApiController]

    [ApiVersion ("1.0")]

    [ApiVersion ("1.1")]

    [ApiVersion ("2.0")]

    javna klasa DefaultController: ControllerBase

    {

        niz [] autori = novi niz []

        {"Joydip Kanjilal", "Steve Smith", "Anand John"};

        [HttpGet]

        javni IEnumerable Get ()

        {

            povratak autora;

        }

    }

Kada podnesete zahtjev za dobivanje od HTTP klijenta, poput Poštara, evo kako će se izvještavati verzije.

Možete prijaviti i zastarjele verzije. Da biste to učinili, trebali biste proslijediti dodatni parametar metodi ApiVersion kako je prikazano u isječku koda koji je dan u nastavku.

[ApiVersion ("1.0", zastarjelo = točno)]

Mapiranje na određenu verziju akcijske metode

Postoji još jedan važan atribut pod nazivom MapToApiVersion. Možete ga koristiti za mapiranje na određenu verziju akcijske metode. Sljedeći isječak koda pokazuje kako se to može postići.

[HttpGet ("{id}")]

[MapToApiVersion ("2.0")]

javni niz Get (int id)

{

   povratak autora [id];

}

Kompletan primjer verziranja API-ja u ASP.NET Coreu

Evo kompletnog izvornog koda DefaultControllera za vašu referencu.

[Ruta ("api / [kontroler]")]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

[ApiVersion ("2.0")]

javna klasa DefaultController: ControllerBase

{

  niz [] autori = novi niz []

  {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

  [HttpGet]

  javni IEnumerable Get ()

  {

      povratak autora;

  }

  [HttpGet ("{id}")]

  [MapToApiVersion ("2.0")]

  javni niz Get (int id)

  {

     povratak autora [id];

  }

}

Strategije izrade verzija API-ja u ASP.NET Coreu

Postoji nekoliko načina na koje možete API-ja verzirati u ASP.NET Core. U ovom ćemo dijelu istražiti svaki od njih.

Informacije o verziji proslijedite kao parametre QueryString

U ovom biste slučaju obično prosljeđivali podatke o verziji kao dio niza upita kao što je prikazano u dolje navedenom URL-u.

//localhost:25718/api/default?api-version=1.0

Informacije o verziji proslijedite u HTTP zaglavlja

Ako želite prosljeđivati ​​podatke o verziji u HTTP zaglavljima, trebali biste ih postaviti u metodi ConfigureServices kako je prikazano u isječku koda koji je dat u nastavku.

usluge.AddApiVersioning (config =>

{

   config.DefaultApiVersion = novi ApiVersion (1, 0);

   config.AssumeDefaultVersionWhenUnspecified = true;

   config.ReportApiVersions = true;

   config.ApiVersionReader = novi HeaderApiVersionReader ("api-verzija");

});

Jednom kada je ovo postavljeno, možete pozvati metodu radnje koja se odnosi na određenu verziju API-ja kao što je prikazano na slici 3.

Informacije o verziji proslijedite u URL

Još jedan način prosljeđivanja podataka o verziji je prenošenje podataka o verziji kao dio rute. Ovo je najjednostavniji način izrade verzija vašeg API-ja, ali postoje određena upozorenja. Prvo, ako koristite ovu strategiju, vaši će klijenti morati ažurirati URL kad god se izda nova verzija API-ja. Slijedom toga, ovaj pristup krši temeljno načelo REST-a koje kaže da se URL određenog resursa nikada ne smije mijenjati.

Da biste implementirali ovu strategiju verziranja, trebali biste navesti podatke o ruti u svom upravljaču kako je prikazano u nastavku.

[Ruta ("api / v {verzija: apiVersion} / [kontroler]")]

Sljedeći popis kodova pokazuje kako to možete postaviti u klasi kontrolera.

[Ruta ("api / v {verzija: apiVersion} / [kontroler]")]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

javna klasa DefaultController: ControllerBase

    {

        niz [] autori = novi niz []

        {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

        [HttpGet]

        javni IEnumerable Get ()

        {

            povratak autora;

        }

        [HttpGet ("{id}")]

        [MapToApiVersion ("2.0")]

        javni niz Get (int id)

        {

            povratak autora [id];

        }

    }

Evo kako možete nazvati zadani HTTP da biste dobili metodu klase DefaultController.

//localhost:25718/api/v1.0/default

Da biste pozvali drugu HTTP GET metodu, tj. Onu koja prihvaća parametar, navedite sljedeće u web pregledniku ili HTTP klijentu kao što je Poštar.

//localhost:25718/api/v2.0/default/1

Obustavite jednu ili više verzija svog API-ja

Pretpostavimo da imate više verzija svog API-ja, ali želite odbaciti jednu ili više njih. To možete učiniti jednostavno - samo trebate navesti zastarjelo svojstvo klase ApiVersionAttribute na true, kao što je prikazano u isječku koda danom dolje.

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1", zastarjelo = točno)]

[ApiVersion ("2.0")]

javna klasa DefaultController: ControllerBase

{

     // Uobičajeni kod

}

Izrada API-ja u ASP.NET Core sada je besprijekorna zahvaljujući uvođenju paketa Microsoft.AspNetCore.Mvc.Versioning. Postoji nekoliko načina za verziju API-ja - samo trebate odlučiti najbolju strategiju na temelju svojih zahtjeva. Za svoj API možete koristiti i više shema verzija. To dodaje veliku fleksibilnost jer klijenti mogu odabrati bilo koju od podržanih shema verzija.

Kako učiniti više u ASP.NET Coreu:

  • Kako koristiti objekte za prijenos podataka u ASP.NET Core 3.1
  • Kako postupati s pogreškama 404 u ASP.NET Core MVC
  • Kako se koristi injekcija ovisnosti u akcijskim filtrima u ASP.NET Core 3.1
  • Kako se koristi obrazac opcija u ASP.NET Core
  • Kako se koristi usmjeravanje krajnje točke u ASP.NET Core 3.0 MVC
  • Kako izvesti podatke u Excel u ASP.NET Core 3.0
  • Kako koristiti LoggerMessage u ASP.NET Core 3.0
  • Kako poslati e-poštu u ASP.NET Core
  • Kako prijaviti podatke na SQL Server u ASP.NET Core
  • Kako rasporediti poslove pomoću Quartz.NET-a u ASP.NET Core
  • Kako vratiti podatke s ASP.NET Core Web API-ja
  • Kako oblikovati podatke o odgovoru u ASP.NET Core
  • Kako konzumirati ASP.NET Core Web API pomoću RestSharp
  • Kako izvesti asinkrne operacije pomoću Dappera
  • Kako koristiti zastavice značajki u ASP.NET Coreu
  • Kako koristiti atribut FromServices u ASP.NET Core
  • Kako raditi s kolačićima u ASP.NET Coreu
  • Kako raditi sa statičkim datotekama u ASP.NET Coreu
  • Kako koristiti URL za prepisivanje Middlewarea u ASP.NET Core
  • Kako implementirati ograničenje brzine u ASP.NET Core
  • Kako koristiti Azure Application Insights u ASP.NET Core
  • Korištenje naprednih značajki NLog u ASP.NET Core
  • Kako postupati s pogreškama u ASP.NET web API-ju
  • Kako implementirati globalno rukovanje iznimkama u ASP.NET Core MVC
  • Kako postupati s null vrijednostima u ASP.NET Core MVC
  • Napredna verzija u ASP.NET Core Web API
  • Kako raditi s uslugama za radnike u ASP.NET Coreu
  • Kako koristiti API zaštite podataka u ASP.NET Core
  • Kako se koristi uvjetni međuprodukt u ASP.NET Coreu
  • Kako raditi sa stanjem sesije u ASP.NET Coreu
  • Kako napisati učinkovite kontrolere u ASP.NET Core