Kako uporabljati različice API v ASP.NET Core

Pri razvoju API-jev morate imeti v mislih eno stvar: spremembe so neizogibne. Ko je vaš API dosegel točko, ko morate dodati več odgovornosti, razmislite o različici API-ja. Zato boste potrebovali strategijo različic.

Obstaja več pristopov k različicam API-jev in vsak od njih ima svoje prednosti in slabosti. V tem članku bomo razpravljali o izzivih različic API-jev in o tem, kako lahko sodelujete z Microsoftovim paketom različic ASP.NET Core MVC za različico API RESTful, vgrajenim v ASP.NET Core. Več o različicah spletnih API-jev si lahko preberete v prejšnjem članku tukaj.

Ustvarite projekt API ASP.NET Core 3.1

Najprej ustvarimo projekt ASP.NET Core v Visual Studio. Ob predpostavki, da je Visual Studio 2019 nameščen v vašem sistemu, sledite spodnjim korakom, da ustvarite nov projekt ASP.NET Core v Visual Studio.

Zaženite Visual Studio IDE.
Kliknite »Ustvari nov projekt«.
V oknu »Ustvari nov projekt« na prikazanih seznamih predlog izberite »Spletna aplikacija ASP.NET Core«.
Kliknite Naprej.
V naslednjem oknu »Konfiguriranje novega projekta« določite ime in mesto novega projekta.
Kliknite Ustvari.
V oknu »Ustvari novo spletno aplikacijo ASP.NET Core« izberite .NET Core kot izvajalno okolje in ASP.NET Core 3.1 (ali novejšo) s spustnega seznama na vrhu. Tukaj bom uporabljal ASP.NET Core 3.1.
Kot predlogo projekta izberite »API«, da ustvarite novo aplikacijo ASP.NET Core API.
Prepričajte se, da sta potrditveni polji »Omogoči podporo za Docker« in »Konfiguriranje za HTTPS« odstranjeni, saj tukaj ne bomo uporabljali teh funkcij.
Prepričajte se, da je preverjanje pristnosti nastavljeno na »Brez preverjanja pristnosti«, saj tudi preverjanja pristnosti ne bomo uporabljali.
Kliknite Ustvari.

To bo ustvarilo nov projekt API-ja ASP.NET Core v Visual Studio. Izberite mapo rešitve Controllers v oknu Solution Explorer in kliknite »Add -> Controller ...«, da ustvarite nov krmilnik z imenom DefaultController.

Izvorno kodo razreda DefaultController zamenjajte z naslednjo kodo.

  [Pot ("api / [krmilnik]")]
  [ApiController]
  javni razred DefaultController: ControllerBase
    {
  niz [] avtorji = nov niz []
  {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};
  [HttpGet]
  javni IEnumerable Get ()
        {
  vrnitev avtorjev;
        }
    }

Ta krmilnik bomo uporabili v naslednjih oddelkih tega članka.

Če želite implementirati različico API-ja v ASP.NET Core, morate storiti naslednje:

Namestite paket za izdajo različic ASP.NET Core MVC.
Konfigurirajte različico API-ja v razredu Startup.
Krmilnike in dejanja označite z ustreznimi atributi.

Namestite paket za izdajo različic ASP.NET Core MVC

ASP.NET Core nudi podporo za različico API-ja že takoj. Če želite izkoristiti različico API-jev, morate samo namestiti paket Microsoft.AspNetCore.Mvc.Versioning iz podjetja NuGet. To lahko storite prek upravitelja paketov NuGet znotraj IDE Visual Studio 2019 ali pa tako, da na konzoli upravitelja paketov NuGet izvedete naslednji ukaz:

Install-Package Microsoft.AspNetCore.Mvc.Versioning

Če uporabljate spletni API ASP.NET, dodajte paket Microsoft.AspNet.WebApi.Versioning.

Konfigurirajte različico API-ja v ASP.NET Core

Zdaj, ko je v vašem projektu nameščen potreben paket za različico API-ja, lahko različico API-jev konfigurirate v metodi ConfigureServices razreda Startup. Naslednji delček kode prikazuje, kako je to mogoče doseči.

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

Ko v API vnesete zahtevo za pridobitev, se prikaže napaka, prikazana na sliki 1.

Če želite odpraviti to napako, lahko pri dodajanju storitev za različico API-ja v vsebnik določite privzeto različico. Morda boste želeli uporabiti tudi privzeto različico, če v zahtevi ni navedena različica. Naslednji delček kode prikazuje, kako lahko nastavite privzeto različico 1.0 z lastnostjo AssumeDefaultVersionWhenUnspecified, če informacije o različici v zahtevi niso na voljo.

services.AddApiVersioning (config =>
{
  config.DefaultApiVersion = nova ApiVersion (1, 0);
  config.AssumeDefaultVersionWhenUnspecified = true;
});

Upoštevajte, kako se glavna in manjša različica posredujeta konstruktorju razreda ApiVersion v času dodelitve privzete različice. Lastnost AssumeDefaultVersionWhenUnspecified lahko vsebuje vrednosti true ali false. Če je res, bo uporabljena privzeta različica, določena pri konfiguriranju različic API, če informacije o različici niso na voljo.

Popolna izvorna koda metode ConfigureServices je navedena spodaj za referenco.

public void ConfigureServices (storitve IServiceCollection)
{
  services.AddControllers ();
  services.AddApiVersioning (config =>
    {
  config.DefaultApiVersion = nova ApiVersion (1, 0);
  config.AssumeDefaultVersionWhenUnspecified = true;
    });
}

Ker niste navedli nobene informacije o različici, bodo vse končne točke imele privzeto različico 1.0.

Prijavite vse podprte različice vašega API-ja

Odjemalcem API-ja boste morda želeli sporočiti vse podprte različice. Če želite to narediti, morate izkoristiti lastnost ReportApiVersions, kot je prikazano v spodnjem delčku kode.

services.AddApiVersioning (config =>
{
  config.DefaultApiVersion = nova ApiVersion (1, 0);
  config.AssumeDefaultVersionWhenUnspecified = true;
  config.ReportApiVersions = true;
});

Uporabite različice v krmilniku in metode dejanja

Zdaj pa v naš krmilnik dodajte nekaj podprtih različic z uporabo atributov, kot je prikazano v spodnjem delčku kode.

  [Pot ("api / [krmilnik]")]
  [ApiController]
  [ApiVersion ("1.0")]
  [ApiVersion ("1.1")]
  [ApiVersion ("2.0")]
  javni razred DefaultController: ControllerBase
    {
  niz [] avtorji = nov niz []
  {"Joydip Kanjilal", "Steve Smith", "Anand John"};
  [HttpGet]
  javni IEnumerable Get ()
        {
  vrnitev avtorjev;
        }
    }

Ko pošljete zahtevo za odjemalca HTTP, kot je Poštar, bomo poročali o različicah.

Lahko tudi prijavite opuščene različice. Če želite to narediti, morate metodi ApiVersion posredovati dodaten parameter, kot je prikazano v spodnjem delčku kode.

[ApiVersion ("1.0", zastarelo = resnično)]

Preslikava na določeno različico akcijske metode

Obstaja še en pomemben atribut z imenom MapToApiVersion. Uporabite ga lahko za preslikavo na določeno različico akcijske metode. Naslednji delček kode prikazuje, kako je to mogoče doseči.

[HttpGet ("{id}")]
[MapToApiVersion ("2.0")]
javni niz Get (int id)
{
  vrni avtorje [id];
}

Popoln primer različic API-ja v ASP.NET Core

Tu je celotna izvorna koda DefaultControllerja za vašo referenco.

[Pot ("api / [krmilnik]")]
[ApiController]
[ApiVersion ("1.0")]
[ApiVersion ("1.1")]
[ApiVersion ("2.0")]
javni razred DefaultController: ControllerBase
{
  niz [] avtorji = nov niz []
  {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};
  [HttpGet]
  javni IEnumerable Get ()
  {
  vrnitev avtorjev;
  }
  [HttpGet ("{id}")]
  [MapToApiVersion ("2.0")]
  javni niz Get (int id)
  {
  vrni avtorje [id];
  }
}

Strategije različic API v ASP.NET Core

Obstaja več načinov, na katere lahko svoj API v različici ASP.NET Core. V tem poglavju bomo raziskali vsako od njih.

Informacije o različici posredujte kot parametre QueryString

V tem primeru bi informacije o različici običajno posredovali kot del niza poizvedbe, kot je prikazano v spodnjem URL-ju.

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

Informacije o različici posredujte v glave HTTP

Če želite informacije o različici posredovati v glavah HTTP, jih nastavite v metodi ConfigureServices, kot je prikazano v spodnjem delčku kode.

services.AddApiVersioning (config =>
{
  config.DefaultApiVersion = nova ApiVersion (1, 0);
  config.AssumeDefaultVersionWhenUnspecified = true;
  config.ReportApiVersions = true;
  config.ApiVersionReader = nov HeaderApiVersionReader ("različica api");
});

Ko je ta nastavljen, lahko prikličete akcijski način, ki se nanaša na določeno različico API-ja, kot je prikazano na sliki 3.

Podatke o različici posredujte v URL

Še en način posredovanja informacij o različici je posredovanje informacij o različici kot del poti. To je najpreprostejši način različice API-ja, vendar obstajajo določena opozorila. Najprej, če uporabljate to strategijo, bodo stranke morale posodobiti URL, ko bo izdana nova različica API-ja. Posledično ta pristop krši temeljno načelo REST, ki pravi, da se URL določenega vira ne sme nikoli spremeniti.

Za izvajanje te strategije različic morate v krmilniku določiti informacije o poti, kot je prikazano spodaj.

[Pot ("api / v {različica: apiVersion} / [krmilnik]")]

Naslednji seznam kod prikazuje, kako lahko to nastavite v razredu krmilnika.

[Pot ("api / v {različica: apiVersion} / [krmilnik]")]
[ApiController]
[ApiVersion ("1.0")]
[ApiVersion ("1.1")]
javni razred DefaultController: ControllerBase
    {
  niz [] avtorji = nov niz []
  {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};
  [HttpGet]
  javni IEnumerable Get ()
        {
  vrnitev avtorjev;
        }
  [HttpGet ("{id}")]
  [MapToApiVersion ("2.0")]
  javni niz Get (int id)
        {
  vrni avtorje [id];
        }
    }

Tukaj je opisano, kako lahko prikličete privzeti HTTP, da dobite metodo razreda DefaultController.

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

Če želite priklicati drugo metodo HTTP GET, to je tisto, ki sprejema parameter, v spletnem brskalniku ali odjemalcu HTTP, kot je Postman, določite naslednje.

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

Opustite eno ali več različic vašega API-ja

Predpostavimo, da imate več različic svojega API-ja, vendar bi radi zavrnili eno ali več. To lahko storite enostavno - samo določite zastarelo lastnost razreda ApiVersionAttribute na true, kot je prikazano v spodnjem delčku kode.

[ApiController]
[ApiVersion ("1.0")]
[ApiVersion ("1.1", zastarelo = resnično)]
[ApiVersion ("2.0")]
javni razred DefaultController: ControllerBase
{
  // Običajna koda
}

Različice API-jev v ASP.NET Core so zdaj brez zapletov zahvaljujoč uvedbi paketa Microsoft.AspNetCore.Mvc.Versioning. Obstaja več načinov za različico API-ja - samo določiti morate najboljšo strategijo glede na vaše zahteve. Za svoj API lahko uporabite tudi več shem različic. To doda veliko prilagodljivosti, saj lahko stranke izberejo katero koli od podprtih shem za različico.