Når du utvikler API-er, bør du huske en ting i tankene: Endring er uunngåelig. Når API-en din har nådd et punkt der du trenger å legge til mer ansvar, bør du vurdere å versjonere API-en din. Derfor trenger du en versjonsstrategi.
Det er flere tilnærminger til versjon av APIer, og hver av dem har sine fordeler og ulemper. Denne artikkelen vil diskutere utfordringene ved API-versjonering og hvordan du kan jobbe med Microsofts ASP.NET Core MVC Versjonspakke til versjon RESTful APIer innebygd i ASP.NET Core. Du kan lese mer om Web API-versjon i min forrige artikkel her.
Opprett et ASP.NET Core 3.1 API-prosjekt
Først og fremst, la oss lage et ASP.NET Core-prosjekt i Visual Studio. Forutsatt at Visual Studio 2019 er installert i systemet ditt, følger du trinnene som er beskrevet nedenfor for å opprette et nytt ASP.NET Core-prosjekt i Visual Studio.
- Start Visual Studio IDE.
- Klikk på "Opprett nytt prosjekt."
- I vinduet "Opprett nytt prosjekt" velger du "ASP.NET Core Web Application" fra listen over maler som vises.
- Klikk på Neste.
- I vinduet “Konfigurer ditt nye prosjekt” som vises, angir du navnet og stedet for det nye prosjektet.
- Klikk på Opprett.
- I vinduet "Create New ASP.NET Core Web Application" velger du .NET Core som kjøretid og ASP.NET Core 3.1 (eller nyere) fra rullegardinlisten øverst. Jeg bruker ASP.NET Core 3.1 her.
- Velg “API” som prosjektmal for å opprette et nytt ASP.NET Core API-program.
- Forsikre deg om at avmerkingsboksene "Aktiver Docker-støtte" og "Konfigurer for HTTPS" ikke er merket av da vi ikke bruker disse funksjonene her.
- Forsikre deg om at autentisering er angitt som “ingen godkjenning”, da vi heller ikke bruker autentisering.
- Klikk på Opprett.
Dette vil opprette et nytt ASP.NET Core API-prosjekt i Visual Studio. Velg Controllers-løsningsmappen i Solution Explorer-vinduet, og klikk "Legg til -> Controller ..." for å opprette en ny kontroller som heter DefaultController.
Erstatt kildekoden til StandardController-klassen med følgende kode.
[Rute ("api / [controller]")][ApiController]
offentlig klasse DefaultController: ControllerBase
{
streng [] forfattere = ny streng []
{"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};
[HttpGet]
offentlig IEnumerable Get ()
{
returnere forfattere;
}
}
Vi bruker denne kontrolleren i de påfølgende delene av denne artikkelen.
For å implementere API-versjonering i ASP.NET Core må du gjøre følgende:
- Installer ASP.NET Core MVC Versjonspakken.
- Konfigurer API-versjonering i Startup-klassen.
- Kommenter kontrollerne og handlingene med passende attributter.
Installer ASP.NET Core MVC Versjonspakken
ASP.NET Core gir støtte for API-versjonering utenom boksen. For å utnytte API-versjonering er alt du trenger å gjøre å installere Microsoft.AspNetCore.Mvc.Versioning-pakken fra NuGet. Du kan gjøre dette enten via NuGet pakkebehandling i Visual Studio 2019 IDE, eller ved å utføre følgende kommando på NuGet pakkebehandler-konsoll:
Installasjonspakke Microsoft.AspNetCore.Mvc.Versioning
Vær oppmerksom på at hvis du bruker ASP.NET Web API, bør du legge til Microsoft.AspNet.WebApi.Versioning-pakken.
Konfigurer API-versjonering i ASP.NET Core
Nå som den nødvendige pakken for versjonering av API-en din er installert i prosjektet ditt, kan du konfigurere API-versjonering i ConfigureServices-metoden i oppstartsklassen. Følgende kodebit illustrerer hvordan dette kan oppnås.
offentlig ugyldighet ConfigureServices (IServiceCollection-tjenester){
tjenester.AddControllers ();
services.AddApiVersioning ();
}
Når du lager en Get-forespørsel til API-en din, vil du bli presentert for feilen vist i figur 1.
For å løse denne feilen kan du angi standardversjonen når du legger til API-versjonstjenestene i containeren. Det kan også være lurt å bruke en standardversjon hvis en versjon ikke er spesifisert i forespørselen. Følgende kodebit viser hvordan du kan angi en standardversjon som 1.0 ved hjelp av AssumeDefaultVersionWhenUnspecified-egenskapen hvis versjonsinformasjon ikke er tilgjengelig i forespørselen.
services.AddApiVersioning (config =>{
config.DefaultApiVersion = ny ApiVersion (1, 0);
config.AssumeDefaultVersionWhenUnspecified = true;
});
Legg merke til hvordan hovedversjonen og mindreversjonen sendes til konstruktøren av ApiVersion-klassen på tidspunktet for tildeling av standardversjonen. Eiendommen AssumeDefaultVersionWhenUnspecified kan inneholde enten sanne eller falske verdier. Hvis det er sant, vil standardversjonen som er spesifisert når du konfigurerer API-versjonering, brukes hvis ingen versjonsinformasjon er tilgjengelig.
Den komplette kildekoden til ConfigureServices-metoden er gitt nedenfor for din referanse.
offentlig ugyldighet ConfigureServices (IServiceCollection-tjenester){
tjenester.AddControllers ();
services.AddApiVersioning (config =>
{
config.DefaultApiVersion = ny ApiVersion (1, 0);
config.AssumeDefaultVersionWhenUnspecified = true;
});
}
Siden du ikke har spesifisert noen versjonsinformasjon, vil alle sluttpunkter ha standardversjonen 1.0.
Rapporter alle støttede versjoner av API-et
Det kan være lurt å fortelle kundene til API-et om alle versjoner som støttes. For å gjøre dette, bør du dra nytte av ReportApiVersions-egenskapen som vist i kodebiten gitt nedenfor.
services.AddApiVersioning (config =>{
config.DefaultApiVersion = ny ApiVersion (1, 0);
config.AssumeDefaultVersionWhenUnspecified = true;
config.ReportApiVersions = true;
});
Bruk versjoner i kontrolleren og handlingsmetoder
La oss nå legge til noen støttede versjoner til kontrolleren vår ved hjelp av attributter som vist i kodebiten gitt nedenfor.
[Rute ("api / [controller]")][ApiController]
[ApiVersion ("1.0")]
[ApiVersion ("1.1")]
[ApiVersion ("2.0")]
offentlig klasse DefaultController: ControllerBase
{
streng [] forfattere = ny streng []
{"Joydip Kanjilal", "Steve Smith", "Anand John"};
[HttpGet]
offentlig IEnumerable Get ()
{
returnere forfattere;
}
}
Når du lager en Get-forespørsel fra en HTTP-klient som Postman, kan du se hvordan versjonene blir rapportert.
Du kan også rapportere de utdaterte versjonene. For å gjøre dette, bør du sende en ekstra parameter til ApiVersion-metoden som vist i kodebiten gitt nedenfor.
[ApiVersion ("1.0", utdatert = sann)]
Kartlegg til en bestemt versjon av en handlingsmetode
Det er en annen viktig egenskap som heter MapToApiVersion. Du kan bruke den til å kartlegge til en bestemt versjon av en handlingsmetode. Følgende kodebit viser hvordan dette kan oppnås.
[HttpGet ("{id}")][MapToApiVersion ("2.0")]
offentlig streng Get (int id)
{
returnere forfattere [id];
}
Komplett API-versjonseksempel i ASP.NET Core
Her er den komplette kildekoden til DefaultController som referanse.
[Rute ("api / [controller]")][ApiController]
[ApiVersion ("1.0")]
[ApiVersion ("1.1")]
[ApiVersion ("2.0")]
offentlig klasse DefaultController: ControllerBase
{
streng [] forfattere = ny streng []
{"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};
[HttpGet]
offentlig IEnumerable Get ()
{
returnere forfattere;
}
[HttpGet ("{id}")]
[MapToApiVersion ("2.0")]
offentlig streng Get (int id)
{
returnere forfattere [id];
}
}
API-versjonsstrategier i ASP.NET Core
Det er flere måter du kan versjonere API på i ASP.NET Core. I denne delen vil vi utforske hver av dem.
Gi versjonsinformasjon som QueryString-parametere
I dette tilfellet sender du vanligvis versjonsinformasjonen som en del av spørringsstrengen som vist i URL-en gitt nedenfor.
//localhost:25718/api/default?api-version=1.0
Send versjonsinformasjon i HTTP-overskriftene
Hvis du skal sende versjonsinformasjon i HTTP-overskriftene, bør du sette den opp i ConfigureServices-metoden som vist i kodebiten gitt nedenfor.
services.AddApiVersioning (config =>{
config.DefaultApiVersion = ny ApiVersion (1, 0);
config.AssumeDefaultVersionWhenUnspecified = true;
config.ReportApiVersions = true;
config.ApiVersionReader = ny HeaderApiVersionReader ("api-versjon");
});
Når dette er konfigurert, kan du påkalle en handlingsmetode som gjelder en bestemt versjon av API som vist i figur 3.
Send versjonsinformasjon i URL-en
Nok en annen metode for å sende versjonsinformasjon er å sende versjonsinformasjon som en del av ruten. Dette er den enkleste måten å versjonere API-en på, men det er visse advarsler. Først og fremst, hvis du bruker denne strategien, må kundene dine oppdatere URL-en når en ny versjon av API-en blir gitt ut. Følgelig bryter denne tilnærmingen et grunnleggende prinsipp for REST som sier at URL-en til en bestemt ressurs aldri skal endres.
For å implementere denne versjonsstrategien, bør du spesifisere ruteinformasjonen i kontrolleren din som vist nedenfor.
[Rute ("api / v {versjon: apiVersion} / [kontroller]")]
Følgende kodeliste viser hvordan du kan sette opp dette i kontrollerklassen din.
[Rute ("api / v {versjon: apiVersion} / [kontroller]")][ApiController]
[ApiVersion ("1.0")]
[ApiVersion ("1.1")]
offentlig klasse DefaultController: ControllerBase
{
streng [] forfattere = ny streng []
{"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};
[HttpGet]
offentlig IEnumerable Get ()
{
returnere forfattere;
}
[HttpGet ("{id}")]
[MapToApiVersion ("2.0")]
offentlig streng Get (int id)
{
returnere forfattere [id];
}
}
Slik kan du ringe standard HTTP for å få metoden i klassen DefaultController.
//localhost:25718/api/v1.0/default
For å påkalle den andre HTTP GET-metoden, dvs. den som godtar en parameter, angir du følgende enten i nettleseren eller en HTTP-klient som Postman.
//localhost:25718/api/v2.0/default/1
Avvikle en eller flere versjoner av API-et
Anta at du har flere versjoner av API-et ditt, men du vil avskrive en eller flere av dem. Du kan gjøre dette enkelt - du trenger bare å spesifisere den utfasede egenskapen til ApiVersionAttribute-klassen til true som vist i kodebiten gitt nedenfor.
[ApiController][ApiVersion ("1.0")]
[ApiVersion ("1.1", utdatert = sann)]
[ApiVersion ("2.0")]
offentlig klasse DefaultController: ControllerBase
{
// Vanlig kode
}
API-versjonering i ASP.NET Core er nå sømløs takket være introduksjonen av Microsoft.AspNetCore.Mvc.Versioning-pakken. Det er flere måter å versjonere API på - du trenger bare å bestemme den beste strategien basert på dine krav. Du kan også bruke flere versjonsskjemaer for API-en. Dette gir mye fleksibilitet siden kundene kan velge hvilken som helst versjonsordning som støttes.
Hvordan gjøre mer i ASP.NET Core:
- Hvordan bruke dataoverføringsobjekter i ASP.NET Core 3.1
- Hvordan håndtere 404 feil i ASP.NET Core MVC
- Hvordan bruke avhengighetsinjeksjon i handlingsfiltre i ASP.NET Core 3.1
- Hvordan bruke alternativmønsteret i ASP.NET Core
- Hvordan bruke endepunktsruting i ASP.NET Core 3.0 MVC
- Slik eksporterer du data til Excel i ASP.NET Core 3.0
- Hvordan bruke LoggerMessage i ASP.NET Core 3.0
- Hvordan sende e-post i ASP.NET Core
- Hvordan logge data til SQL Server i ASP.NET Core
- Hvordan planlegge jobber med Quartz.NET i ASP.NET Core
- Hvordan returnere data fra ASP.NET Core Web API
- Hvordan formatere svardata i ASP.NET Core
- Slik bruker du et ASP.NET Core Web API ved hjelp av RestSharp
- Hvordan utføre asynkroniseringsoperasjoner ved hjelp av Dapper
- Hvordan bruke funksjonsflagg i ASP.NET Core
- Hvordan bruke attributtet FromServices i ASP.NET Core
- Hvordan jobbe med informasjonskapsler i ASP.NET Core
- Hvordan jobbe med statiske filer i ASP.NET Core
- Hvordan bruke URL Rewriting Middleware i ASP.NET Core
- Hvordan implementere hastighetsbegrensning i ASP.NET Core
- Hvordan bruke Azure Application Insights i ASP.NET Core
- Bruker avanserte NLog-funksjoner i ASP.NET Core
- Hvordan håndtere feil i ASP.NET Web API
- Hvordan implementere global unntaksbehandling i ASP.NET Core MVC
- Hvordan håndtere nullverdier i ASP.NET Core MVC
- Avansert versjonering i ASP.NET Core Web API
- Hvordan jobbe med arbeidstjenester i ASP.NET Core
- Hvordan bruke API for databeskyttelse i ASP.NET Core
- Hvordan bruke betinget mellomvare i ASP.NET Core
- Hvordan jobbe med økttilstand i ASP.NET Core
- Hvordan skrive effektive kontrollere i ASP.NET Core