Du bør alltid versjon av web-API-en din samtidig som du beholder så mye av samme URI som mulig. Tenk deg en situasjon der du har et web-API som er oppe og går i produksjon og blir fortært av brukere. Anta at du trenger mer funksjonalitet i Web API, men du må holde den eksisterende funksjonaliteten intakt. Du kan ha noen få brukere som fortsatt trenger den gamle API-en, mens andre trenger en versjon med nye eller utvidede funksjoner. Dette er nøyaktig hvor Web API-versjonering kommer til unnsetning.
Du kan versjon Web API på en av følgende måter:
- Bruk URL-er: Versjonsinformasjon er spesifisert i URL-en som en spørringsstreng.
- Bruk overskrifter for egendefinerte forespørsler: Versjonsinformasjon for kontrolleren din er spesifisert i forespørselsoverskriften, uten behov for endringer i URL-en.
- Bruk Godta overskrifter: Godta overskrifter definerer vanligvis medietypen og tegnkodningene. Du kan sende versjonsinformasjon for web-API-en din via godta overskrifter uten å måtte endre URL-adressen.
Versjonering av web-API ved hjelp av URL-er
Tenk på følgende Web API-kontrollere, som har fått navnetForfattereV1Controller og ForfattereV2Controller henholdsvis.
public class AuthorsV1Controller: ApiController{
[HttpGet]
offentlige IEnumerable GetAuthors ()
{
returner ny streng [] {"Joydip Kanjilal", "Gerben Wierda"};
}
}
offentlig klasse ForfattereV2Controller: ApiController
{
[HttpGet]
offentlige IEnumerable GetAuthors ()
{
returner ny streng [] {"Joydip Kanjilal, INDIA", "Gerben Wierda, Nederland"};
}
}
For å forenkle denne illustrasjonen har jeg innarbeidet en metode som heter GetAuthors () i hver kontroller. Samtidig som GetAuthors () i ForfattereV1Controller returnerer bare forfatternavnene, GetAuthors () i ForfattereV2Controller (den nye versjonen) returnerer forfatternavnene sammen med navnene på landene forfatterne er bosatt i.
Følgende kodebit viser hvordan de to kontrollerne bruker Register-metoden til WebApiConfig klasse.
config.Routes.MapHttpRoute (navn: "WebAPIV1",
routeTemplate: "api / v1 / {controller} / {id}",
standardverdier: ny {controller = "AuthorsV1Controller", action = "GetAuthors", id = RouteParameter.Optional}
);
config.Routes.MapHttpRoute (
navn: "WebAPIV2",
routeTemplate: "api / v2 / {controller} / {id}",
standardverdier: ny {controller = "AuthorsV2Controller", action = "GetAuthors", id = RouteParameter.Optional}
);
Du kan nå påberope Web API-metoden GetAuthors ved hjelp av følgende URL.
// localhost / WebAPI / api / v1 / Forfattere / GetAuthors
Versjonering av Web API ved hjelp av forespørselstittelen
Du kan også implementere versjon av Web API ved hjelp av forespørselstittelen. For å oppnå dette må du implementere en tilpasset klasse som utvider StandardHttpControllerSelector klasse, deretter overstyre Velg kontroller i din tilpassede klasse. Merk at StandardHttpControllerSelector klasse implementerer IHttpControllerSelector grensesnitt.Velg kontroller ringer GetControllerName internt og godtar en forekomst av HttpRequestMessage som parameter.
Følgende kodebit illustrerer hvordan du kan hente versjonsinformasjon fra forespørselstittelen.
private string GetControllerVersionFromRequestHeader (HttpRequestMessage forespørsel){
var acceptHeader = request.Headers.Accept;
const string headerName = "Versjon";
streng controllerVersjon = streng.Empty;
if (request.Headers.Contains (headerName))
{
controllerVersion = "V" + request.Headers.GetValues (headerName) .First ();
}
retur controllerVersjon;
}
Versjonering av web-API ved hjelp av aksepthodet
Følgende metode viser hvordan du kan hente versjonsinformasjon for web-API-et ditt fra godkjenningshodet. Metoden sjekker MIME-typen og returnerer versjonsinformasjonen på riktig måte. Hvis medietypen ikke er det søknad / json, blir standardversjonen returnert som V1.
private string GetControllerVersionFromAcceptHeader (HttpRequestMessage forespørsel){
var acceptHeader = request.Headers.Accept;
streng controllerVersjon = streng.Empty;
foreach (var mime in acceptHeader)
{
if (mime.MediaType.Equals ("application / json"))
{
NameValueHeaderValue version = mime.Parameters.FirstOrDefault (v => v.Name.Equals ("Version", StringComparison.OrdinalIgnoreCase));
controllerVersion = "V" + versjon.Value.ToString ();
retur controllerVersjon;
}
}
returner "V1";
}
Du kan påkalle Web API fra Fiddler ved å sende godkjenningshodet som vist nedenfor.
Godta: applikasjon / json; charset = utf-8; versjon = 2
Følgende kodeliste illustrerer hvordan du kan overstyre Velg kontroller for å velge en kontroller dynamisk. Legg merke til hvordan GetControllerVersionFromRequestHeader har blitt brukt. Hvis du vil hente kontrollerversjonen fra godkjenningshodet, bør du bruke GetControllerVersionFromAcceptHeader i stedet.
offentlig overstyring HttpControllerDescriptor SelectController (HttpRequestMessage-forespørsel){
prøve
{
streng controllerName = base.GetControllerName (forespørsel);
var controllers = GetControllerMapping ();
var routeData = request.GetRouteData ();
string controllerVersion = GetControllerVersionFromRequestHeader (forespørsel);
controllerName = String.Format ("{0} {1}", controllerName, controllerVersion);
HttpControllerDescriptor controllerDescriptor;
if (! controllers.TryGetValue (controllerName, out controllerDescriptor))
{
string message = "Ingen HTTP-ressurs ble funnet som samsvarer med den angitte forespørsel URI {0}";
kaste nye HttpResponseException (forespørsel.CreateErrorResponse (System.Net.HttpStatusCode.NotFound, String.Format (melding, forespørsel.RequestUri)));
}
retur controllerDescriptor;
}
fangst (Unntak eks)
{
kaste ny HttpResponseException (forespørsel.CreateErrorResponse (System.Net.HttpStatusCode.NotFound, String.Format (f.eks. Melding, forespørsel. RequestUri)));
}
}
Du bør legge til følgende linje i Register-metoden i WebApiConfig-klassen for å gi støtte for valg av kontroller ved kjøretid.
config.Services.Rlace (typeof (IHttpControllerSelector), new ControllerSelector ((config)));
Du kan nå bruke Fiddler til å teste web-API-et ditt - bruk komponistfanen til Fiddler og oppgi URL- og versjonsinformasjonen etter behov. Hvis du vil at versjon 2 av Web API-kontrolleren skal påberopes, bør du spesifisere Versjon: 2 når du skriver forespørselshodeinformasjonen i fanen Komponist i Fiddler.
