Kā izmantot API versijas ASP.NET Core

Izstrādājot API, jums jāpatur prātā viena lieta: izmaiņas ir neizbēgamas. Kad jūsu API ir sasniedzis punktu, kurā jums jāpievieno vairāk pienākumu, jums vajadzētu apsvērt iespēju versiju par API. Tādējādi jums būs nepieciešama versiju izstrādes stratēģija.

API versijai ir vairākas pieejas, un katrai no tām ir savi plusi un mīnusi. Šajā rakstā tiks aplūkotas API versiju problēmas un tas, kā jūs varat strādāt ar Microsoft ASP.NET Core MVC versiju pakotnes versiju RESTful API, kas iebūvēta ASP.NET Core. Vairāk par Web API versiju veidošanu varat izlasīt manā iepriekšējā rakstā šeit.

Izveidojiet ASP.NET Core 3.1 API projektu

Vispirms izveidosim ASP.NET Core projektu Visual Studio. Pieņemot, ka Visual Studio 2019 ir instalēta jūsu sistēmā, veiciet tālāk norādītās darbības, lai izveidotu jaunu ASP.NET Core projektu Visual Studio.

Palaidiet Visual Studio IDE.
Noklikšķiniet uz “Izveidot jaunu projektu”.
Logā “Izveidot jaunu projektu” parādīto veidņu sarakstā atlasiet “ASP.NET Core Web Application”.
Noklikšķiniet uz Tālāk.
Nākamajā logā “Konfigurēt jauno projektu” norādiet jaunā projekta nosaukumu un vietu.
Noklikšķiniet uz Izveidot.
Logā “Izveidot jaunu ASP.NET Core tīmekļa lietojumprogrammu” augšpusē esošajā nolaižamajā sarakstā atlasiet .NET Core kā izpildlaiku un ASP.NET Core 3.1 (vai jaunāku). Es šeit izmantošu ASP.NET Core 3.1.
Atlasiet “API” kā projekta veidni, lai izveidotu jaunu ASP.NET Core API lietojumprogrammu.
Pārliecinieties, vai nav atzīmētas izvēles rūtiņas “Iespējot Docker atbalstu” un “Konfigurēt HTTPS”, jo mēs šeit neizmantosim šīs funkcijas.
Pārliecinieties, ka autentifikācija ir iestatīta kā “Nav autentifikācijas”, jo mēs arī neizmantosim autentifikāciju.
Noklikšķiniet uz Izveidot.

Tādējādi Visual Studio tiks izveidots jauns ASP.NET Core API projekts. Logā Solution Explorer atlasiet Controllers solution mapi un noklikšķiniet uz “Add -> Controller…”, lai izveidotu jaunu kontrolleri ar nosaukumu DefaultController.

Klases DefaultController avota kodu aizstājiet ar šādu kodu.

  [Maršruts ("api / [kontrolieris]")]
  [ApiController]
  publiskā klase DefaultController: ControllerBase
    {
  virkne [] autori = jauna virkne []
  {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};
  [HttpGet]
  public IEnumerable Get ()
        {
  atgriešanās autori;
        }
    }

Mēs izmantosim šo kontrolieri nākamajās šī raksta sadaļās.

Lai ieviestu API versijas ASP.NET Core, jums jāveic šādas darbības:

Instalējiet ASP.NET Core MVC versiju pakotni.
Konfigurējiet API versijas Startup klasē.
Atzīmējiet kontrolierus un darbības ar atbilstošiem atribūtiem.

Instalējiet ASP.NET Core MVC versiju pakotni

ASP.NET Core nodrošina atbalstu API versijai jau pašā komplektācijā. Lai izmantotu API versijas, viss, kas jums jādara, ir instalēt Microsoft.AspNetCore.Mvc.Versioning paketi no NuGet. To var izdarīt, izmantojot NuGet pakotņu pārvaldnieku Visual Studio 2019 IDE, vai arī izpildot šādu komandu NuGet pakotņu pārvaldnieka konsolē:

Instalācijas pakotne Microsoft.AspNetCore.Mvc.Versioning

Ņemiet vērā, ka, ja izmantojat ASP.NET Web API, jums jāpievieno pakete Microsoft.AspNet.WebApi.Versioning.

Konfigurējiet API versijas programmā ASP.NET Core

Tagad, kad projektā ir instalēta nepieciešamā API versiju pakotne, API versijas var konfigurēt Startup klases ConfigureServices metodē. Šis koda fragments parāda, kā to var panākt.

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

Veicot API saņemšanas pieprasījumu, jums tiks parādīta kļūda, kas parādīta 1. attēlā.

Lai novērstu šo kļūdu, konteineram pievienojot API versiju veidošanas pakalpojumus, varat norādīt noklusējuma versiju. Varat arī izmantot noklusējuma versiju, ja pieprasījumā nav norādīta versija. Šis koda fragments parāda, kā noklusējuma versiju var iestatīt kā 1,0, izmantojot rekvizītu AssumeDefaultVersionWhenUnspecified, ja informācija par versiju nav pieejama pieprasījumā.

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

Ievērojiet, kā galvenā versija un mazākā versija tiek nodota ApiVersion klases konstruktoram noklusējuma versijas piešķiršanas laikā. Rekvizītā AssumeDefaultVersionWhenUnspecified var būt gan patiesas, gan nepatiesas vērtības. Ja tā ir taisnība, tiks izmantota noklusējuma versija, kas norādīta, konfigurējot API versijas, ja informācija par versiju nav pieejama.

Pilns ConfigureServices metodes avota kods ir norādīts zemāk.

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

Tā kā neesat norādījis informāciju par versiju, visiem galapunktiem būs noklusējuma versija 1.0.

Ziņot par visām jūsu API atbalstītajām versijām

Iespējams, vēlēsities informēt API klientus par visām atbalstītajām versijām. Lai to izdarītu, jums vajadzētu izmantot rekvizīta ReportApiVersions priekšrocības, kā parādīts tālāk sniegtajā koda fragmentā.

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

Izmantojiet kontroliera un darbības metožu versijas

Tagad pievienosim dažas atbalstītās versijas mūsu kontrolierim, izmantojot atribūtus, kā parādīts tālāk sniegtajā koda fragmentā.

  [Maršruts ("api / [kontrolieris]")]
  [ApiController]
  [ApiVersion ("1.0")]
  [ApiVersion ("1.1")]
  [ApiVersion ("2.0")]
  publiskā klase DefaultController: ControllerBase
    {
  virkne [] autori = jauna virkne []
  {"Joydip Kanjilal", "Steve Smith", "Anand John"};
  [HttpGet]
  public IEnumerable Get ()
        {
  atgriešanās autori;
        }
    }

Veicot pieprasījumu no HTTP klienta, piemēram, Pastnieka, saņemiet pieprasījumu par versijām.

Varat ziņot arī par novecojušajām versijām. Lai to izdarītu, ApiVersion metodei jānodod papildu parametrs, kā parādīts tālāk sniegtajā koda fragmentā.

[ApiVersion ("1.0", novecojis = patiess)]

Kartējiet uz konkrētu darbības metodes versiju

Ir vēl viens svarīgs atribūts ar nosaukumu MapToApiVersion. To var izmantot, lai piesaistītu konkrētu darbības metodes versiju. Šis koda fragments parāda, kā to var paveikt.

[HttpGet ("{id}")]
[MapToApiVersion ("2.0")]
publiskā virkne Get (int id)
{
  atgriešanās autori [id];
}

Pilnīgs API versijas piemērs ASP.NET Core

Šeit ir pilns DefaultController avota kods jūsu atsaucei.

[Maršruts ("api / [kontrolieris]")]
[ApiController]
[ApiVersion ("1.0")]
[ApiVersion ("1.1")]
[ApiVersion ("2.0")]
publiskā klase DefaultController: ControllerBase
{
  virkne [] autori = jauna virkne []
  {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};
  [HttpGet]
  public IEnumerable Get ()
  {
  atgriešanās autori;
  }
  [HttpGet ("{id}")]
  [MapToApiVersion ("2.0")]
  publiskā virkne Get (int id)
  {
  atgriešanās autori [id];
  }
}

API versiju noteikšanas stratēģijas ASP.NET Core

Ir vairāki veidi, kā varat API versiju pārveidot ASP.NET Core. Šajā sadaļā mēs izpētīsim katru no tiem.

Pāriet uz versijas informāciju kā QueryString parametrus

Šajā gadījumā informācija par versiju parasti tiek nodota kā vaicājuma virknes sastāvdaļa, kā parādīts zemāk norādītajā URL.

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

Pārraidiet informāciju par versiju HTTP galvenēs

Ja informācija par versiju jānodod HTTP galvenēs, tā jāiestata ConfigureServices metodē, kā parādīts tālāk sniegtajā koda fragmentā.

services.AddApiVersioning (config =>
{
  config.DefaultApiVersion = jauna ApiVersion (1, 0);
  config.AssumeDefaultVersionWhenUnspecified = true;
  config.ReportApiVersions = true;
  config.ApiVersionReader = new HeaderApiVersionReader ("api versija");
});

Kad tas ir iestatīts, varat izmantot darbības metodi, kas attiecas uz noteiktu API versiju, kā parādīts 3. attēlā.

Pārsūtiet informāciju par versiju URL

Vēl viena informācijas par versiju nodošanas metode ir informācijas par versiju nodošana maršruta ietvaros. Šis ir vienkāršākais API versijas veidošanas veids, taču ir noteikti iebildumi. Pirmkārt, ja izmantojat šo stratēģiju, jūsu klientiem būs jāatjaunina URL ikreiz, kad tiek izlaista jauna API versija. Līdz ar to šī pieeja pārkāpj REST pamatprincipu, kas nosaka, ka konkrēta resursa URL nekad nedrīkst mainīties.

Lai ieviestu šo versiju noteikšanas stratēģiju, kontrolierī jānorāda maršruta informācija, kā parādīts zemāk.

[Maršruts ("api / v {versija: apiVersion} / [kontrolieris]")]

Šis kodu saraksts parāda, kā jūs varat to iestatīt savā kontroliera klasē.

[Maršruts ("api / v {versija: apiVersion} / [kontrolieris]")]
[ApiController]
[ApiVersion ("1.0")]
[ApiVersion ("1.1")]
publiskā klase DefaultController: ControllerBase
    {
  virkne [] autori = jauna virkne []
  {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};
  [HttpGet]
  public IEnumerable Get ()
        {
  atgriešanās autori;
        }
  [HttpGet ("{id}")]
  [MapToApiVersion ("2.0")]
  publiskā virkne Get (int id)
        {
  atgriešanās autori [id];
        }
    }

Lūk, kā jūs varat izsaukt noklusējuma HTTP, lai iegūtu DefaultController klases metodi.

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

Lai izsauktu citu HTTP GET metodi, t.i., metodi, kas pieņem parametru, tīmekļa pārlūkprogrammā vai HTTP klientā, piemēram, Pastnieks, norādiet sekojošo.

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

Pārtrauciet vienu vai vairākas jūsu API versijas

Pieņemsim, ka jums ir vairākas jūsu API versijas, taču vēlaties novecot vienu vai vairākas no tām. To var izdarīt vienkārši - jums vienkārši jānorāda ApiVersionAttribute klases rekvizīts true, kā parādīts tālāk sniegtajā koda fragmentā.

[ApiController]
[ApiVersion ("1.0")]
[ApiVersion ("1.1", novecojis = patiess)]
[ApiVersion ("2.0")]
publiskā klase DefaultController: ControllerBase
{
  // Parastais kods
}

API versijas ASP.NET Core tagad ir nevainojamas, pateicoties Microsoft.AspNetCore.Mvc.Versioning pakotnes ieviešanai. API versijai ir vairāki veidi - jums vienkārši jāizlemj labākā stratēģija, pamatojoties uz jūsu prasībām. Savai API varat izmantot arī vairākas versiju shēmas. Tas piešķir daudz elastības, jo klienti var izvēlēties jebkuru no atbalstītajām versiju shēmām.