Měli byste vždy své webové rozhraní API aktualizovat a současně zachovat co nejvíce stejného URI, jak je to možné. Představte si situaci, kdy máte webové API, které je v provozu a běží ve výrobě a je spotřebováváno uživateli. Nyní předpokládejme, že potřebujete více funkcí ve webovém rozhraní API, ale musíte zachovat stávající funkce beze změny. Možná máte několik uživatelů, kteří stále potřebují staré API, zatímco ostatní budou potřebovat verzi s novými nebo rozšířenými funkcemi. To je přesně místo, kde dochází k záchraně verzí webového API.
Webové rozhraní API můžete verzovat jedním z následujících způsobů:
- Použít adresy URL: Informace o verzi jsou v adrese URL zadány jako řetězec dotazu.
- Použít vlastní záhlaví požadavku: Informace o verzi pro váš řadič jsou uvedeny v záhlaví požadavku bez nutnosti jakýchkoli změn v adrese URL.
- Použít Přijmout záhlaví: Přijmout záhlaví obecně definuje typ média a kódování znaků. Informace o verzi svého webového rozhraní API můžete předat prostřednictvím přijetí záhlaví, aniž byste museli měnit adresu URL.
Verze webového rozhraní API pomocí adres URL
Zvažte následující řadiče webového rozhraní API, které byly pojmenoványAuthorsV1Controller a AuthorsV2Controller resp.
veřejná třída AuthorsV1Controller: ApiController{
[HttpGet]
veřejné IEnumerable GetAuthors ()
{
vrátit nový řetězec [] {"Joydip Kanjilal", "Gerben Wierda"};
}
}
veřejná třída AuthorsV2Controller: ApiController
{
[HttpGet]
veřejné IEnumerable GetAuthors ()
{
vrátit nový řetězec [] {"Joydip Kanjilal, INDIE", "Gerben Wierda, Nizozemsko"};
}
}
Pro zjednodušení této ilustrace jsem začlenil metodu s názvem GetAuthors () v každém řadiči. Zatímco GetAuthors () v AuthorsV1Controller vrací pouze jména autorů, GetAuthors () v AuthorsV2Controller (nová verze) vrátí jména autorů spolu se jmény zemí, ve kterých se autoři nacházejí.
Následující fragment kódu ukazuje, jak dva řadiče používají Register metodu WebApiConfig třída.
config.Routes.MapHttpRoute (název: "WebAPIV1",
routeTemplate: "api / v1 / {controller} / {id}",
výchozí: nový {controller = "AuthorsV1Controller", action = "GetAuthors", id = RouteParameter.Optional}
);
config.Routes.MapHttpRoute (
název: "WebAPIV2",
routeTemplate: "api / v2 / {controller} / {id}",
výchozí: nový {controller = "AuthorsV2Controller", action = "GetAuthors", id = RouteParameter.Optional}
);
Nyní můžete vyvolat metodu webového rozhraní API GetAuthors pomocí následující adresy URL.
// localhost / WebAPI / api / v1 / Autoři / GetAuthors
Verze webového API pomocí záhlaví požadavku
Můžete také implementovat správu verzí webového rozhraní API pomocí záhlaví požadavku. Chcete-li toho dosáhnout, musíte implementovat vlastní třídu, která rozšiřuje DefaultHttpControllerSelector třídy, pak přepsat SelectController ve vaší vlastní třídě. Všimněte si, že DefaultHttpControllerSelector třída implementuje IHttpControllerSelector rozhraní.SelectController hovory GetControllerName interně a přijímá instanci HttpRequestMessage jako parametr.
Následující fragment kódu ukazuje, jak můžete načíst informace o verzi z hlavičky požadavku.
soukromý řetězec GetControllerVersionFromRequestHeader (požadavek HttpRequestMessage){
var acceptHeader = request.Headers.Accept;
const řetězec headerName = "Verze";
string controllerVersion = string.Empty;
if (request.Headers.Contains (headerName))
{
controllerVersion = "V" + request.Headers.GetValues (headerName) .First ();
}
return controllerVersion;
}
Verze webového rozhraní API pomocí hlavičky Přijmout
Následující metoda ukazuje, jak můžete z hlavičky přijmout načíst informace o verzi pro vaše webové API. Metoda kontroluje typ MIME a odpovídajícím způsobem vrací informace o verzi. Pokud typ média není aplikace / JSON, výchozí verze je vrácena jako V1.
soukromý řetězec GetControllerVersionFromAcceptHeader (požadavek HttpRequestMessage){
var acceptHeader = request.Headers.Accept;
string controllerVersion = string.Empty;
foreach (var mime v acceptHeader)
{
if (mime.MediaType.Equals ("application / json"))
{
NameValueHeaderValue verze = mime.Parameters.FirstOrDefault (v => v.Name.Equals ("Verze", StringComparison.OrdinalIgnoreCase));
controllerVersion = "V" + version.Value.ToString ();
return controllerVersion;
}
}
návrat "V1";
}
Webové rozhraní API můžete vyvolat z Fiddleru předáním hlavičky přijetí, jak je znázorněno níže.
Přijmout: application / json; charset = utf-8; verze = 2
Následující výpis kódu ukazuje, jak můžete přepsat SelectController dynamicky vybrat řadič. Všimněte si jak GetControllerVersionFromRequestHeader byl užíván. Pokud chcete načíst verzi ovladače z hlavičky přijetí, měli byste využít GetControllerVersionFromAcceptHeader namísto.
veřejné přepsání HttpControllerDescriptor SelectController (požadavek HttpRequestMessage){
Snaž se
{
řetězec controllerName = base.GetControllerName (požadavek);
var controllers = GetControllerMapping ();
var routeData = request.GetRouteData ();
string controllerVersion = GetControllerVersionFromRequestHeader (požadavek);
controllerName = String.Format ("{0} {1}", controllerName, controllerVersion);
HttpControllerDescriptor controllerDescriptor;
if (! controllers.TryGetValue (controllerName, out controllerDescriptor))
{
string message = "Nebyl nalezen žádný prostředek HTTP, který odpovídá zadanému identifikátoru URI požadavku {0}";
hodit novou HttpResponseException (request.CreateErrorResponse (System.Net.HttpStatusCode.NotFound, String.Format (zpráva, request.RequestUri)));
}
návratový řadič Deskriptor;
}
úlovek (výjimka mimo)
{
hodit novou HttpResponseException (request.CreateErrorResponse (System.Net.HttpStatusCode.NotFound, String.Format (ex.Message, request.RequestUri)));
}
}
Následující řádek byste měli přidat do metody Register třídy WebApiConfig, abyste poskytli podporu pro výběr řadiče za běhu.
config.Services.Replace (typeof (IHttpControllerSelector), nový ControllerSelector ((config)));
Nyní můžete použít Fiddler k otestování vašeho webového API - použijte záložku Fiddler na kartě skladatel a podle potřeby uveďte informace o adrese URL a verzi. Pokud chcete, aby byla vyvolána verze 2 vašeho řadiče webového rozhraní API, měli byste zadat Verze: 2 při skládání informací záhlaví požadavku na kartě Skladatel v nástroji Fiddler.
