Du skal altid versionere din Web API, samtidig med at du holder så meget af den samme URI som muligt. Forestil dig en situation, hvor du har en web-API, der er i gang i produktion og forbruges af brugere. Antag nu, at du har brug for mere funktionalitet i Web API, men alligevel skal holde den eksisterende funktionalitet intakt. Du kan have et par brugere, der stadig har brug for den gamle API, mens andre har brug for en version med nye eller udvidede funktioner. Dette er præcis, hvor Web API-versionering kommer til undsætning.
Du kan versionere din Web API på en af følgende måder:
- Brug URL'er: Versionoplysninger er angivet i URL'en som en forespørgselsstreng.
- Brug brugerdefinerede anmodningsoverskrifter: Oplysninger om version til din controller er specificeret i anmodningsoverskriften uden behov for ændringer i URL-adressen.
- Brug Accepter overskrifter: Accepter overskrifter definerer generelt medietype og tegnkodning. Du kan videregive versionoplysninger til din Web API via accept overskrifter uden at skulle ændre URL'en.
Versioning af Web API ved hjælp af URL'er
Overvej følgende Web API-controllere, som er blevet navngivetForfattereV1Controller og ForfattereV2Controller henholdsvis.
public class AuthorsV1Controller: ApiController{
[HttpGet]
offentlige IEnumerable GetAuthors ()
{
returner ny streng [] {"Joydip Kanjilal", "Gerben Wierda"};
}
}
public class AuthorsV2Controller: ApiController
{
[HttpGet]
offentlige IEnumerable GetAuthors ()
{
returner ny streng [] {"Joydip Kanjilal, INDIEN", "Gerben Wierda, Holland"};
}
}
For at forenkle denne illustration har jeg indarbejdet en metode, der hedder GetAuthors () i hver controller. Mens GetAuthors () i ForfattereV1Controller returnerer kun forfatternavne, GetAuthors () i ForfattereV2Controller (den nye version) returnerer forfatternavnene sammen med navnene på de lande, hvor forfatterne er bosiddende.
Følgende kodestykke viser, hvordan de to controllere bruger registreringsmetoden til WebApiConfig klasse.
config.Routes.MapHttpRoute (navn: "WebAPIV1",
routeTemplate: "api / v1 / {controller} / {id}",
standardindstillinger: ny {controller = "AuthorsV1Controller", action = "GetAuthors", id = RouteParameter.Optional}
);
config.Routes.MapHttpRoute (
navn: "WebAPIV2",
routeTemplate: "api / v2 / {controller} / {id}",
standardindstillinger: ny {controller = "AuthorsV2Controller", action = "GetAuthors", id = RouteParameter.Optional}
);
Du kan nu påberåbe Web API-metoden GetAuthors ved hjælp af følgende URL.
// localhost / WebAPI / api / v1 / Forfattere / GetAuthors
Versioning af Web API ved hjælp af anmodningsoverskriften
Du kan også implementere Web API-versionering ved hjælp af anmodningsoverskriften. For at opnå dette skal du implementere en brugerdefineret klasse, der udvider StandardHttpControllerSelector klasse, og tilsidesæt derefter Vælg kontrol i din brugerdefinerede klasse. Bemærk, at StandardHttpControllerSelector klasse implementerer IHttpControllerSelector interface.Vælg kontrol opkald GetControllerName internt og accepterer en forekomst af HttpRequestMessage som parameter.
Følgende kodestykke illustrerer, hvordan du kan hente versionoplysninger fra anmodningsoverskriften.
privat streng GetControllerVersionFromRequestHeader (HttpRequestMessage anmodning){
var acceptHeader = anmodning.Headers.Accept;
const string headerName = "Version";
streng controllerVersion = streng.Empty;
hvis (anmodning.Headers.Contains (headerName))
{
controllerVersion = "V" + request.Headers.GetValues (headerName) .First ();
}
return controllerVersion;
}
Versioning Web API ved hjælp af accept header
Følgende metode viser, hvordan du kan hente versionoplysninger til din Web API fra acceptoverskriften. Metoden kontrollerer MIME-typen og returnerer versionsoplysningerne korrekt. Hvis medietypen ikke er det ansøgning / json, returneres standardversionen som V1.
privat streng GetControllerVersionFromAcceptHeader (HttpRequestMessage anmodning){
var acceptHeader = anmodning.Headers.Accept;
streng controllerVersion = streng.Empty;
foreach (var mime in acceptHeader)
{
hvis (mime.MediaType.Equals ("applikation / json"))
{
NameValueHeaderValue version = mime.Parameters.FirstOrDefault (v => v.Name.Equals ("Version", StringComparison.OrdinalIgnoreCase));
controllerVersion = "V" + version.Value.ToString ();
return controllerVersion;
}
}
returner "V1";
}
Du kan påkalde din Web API fra Fiddler ved at sende accept-overskriften som vist nedenfor.
Accepter: applikation / json; charset = utf-8; version = 2
Følgende kodeliste illustrerer, hvordan du kan tilsidesætte Vælg kontrol for at vælge en controller dynamisk. Bemærk hvordan GetControllerVersionFromRequestHeader er blevet brugt. Hvis du vil hente controller-versionen fra acceptoverskriften, skal du udnytte GetControllerVersionFromAcceptHeader i stedet.
offentlig tilsidesættelse af HttpControllerDescriptor SelectController (HttpRequestMessage-anmodning){
prøve
{
streng controllerName = base.GetControllerName (anmodning);
var controllere = GetControllerMapping ();
var routeData = request.GetRouteData ();
streng controllerVersion = GetControllerVersionFromRequestHeader (anmodning);
controllerName = String.Format ("{0} {1}", controllerName, controllerVersion);
HttpControllerDescriptor controllerDescriptor;
if (! controllers.TryGetValue (controllerName, out controllerDescriptor))
{
string message = "Der blev ikke fundet nogen HTTP-ressource, der matcher den angivne URI {0}";
smid ny HttpResponseException (anmodning.CreateErrorResponse (System.Net.HttpStatusCode.NotFound, String.Format (besked, anmodning.RequestUri)));
}
return controllerDescriptor;
}
fangst (undtagelse ex)
{
smid ny HttpResponseException (anmodning.CreateErrorResponse (System.Net.HttpStatusCode.NotFound, String.Format (f.eks. besked, anmodning.RequestUri)));
}
}
Du skal tilføje følgende linje i Register-metoden i WebApiConfig-klassen for at give support til valg af controller under kørsel.
config.Services.Replace (typeof (IHttpControllerSelector), ny ControllerSelector ((config)));
Du kan nu bruge Fiddler til at teste din web-API - brug komponistfanen i Fiddler og angiv URL'en og versionoplysningerne efter behov. Hvis du vil påberåbe version 2 af din Web API-controller, skal du angive Version: 2 når du sammensætter anmodningens headeroplysninger under fanen Composer i Fiddler.
