Webové rozhranie API by ste mali mať vždy vo verzii, pričom by ste mali súčasne uchovávať čo najviac rovnakého identifikátora URI. Predstavte si situáciu, že máte webové API, ktoré je v prevádzke a je produkčne využívané používateľmi. Teraz predpokladajme, že potrebujete viac funkcií vo webovom rozhraní API, ale musíte zachovať nedotknuté existujúce funkcie. Možno budete mať niekoľko používateľov, ktorí stále potrebujú staré API, zatiaľ čo iní budú potrebovať verziu s novými alebo rozšírenými funkciami. Presne tu prichádza na rad správa verzií webového API.
Verziu webového rozhrania API môžete vytvoriť jedným z nasledujúcich spôsobov:
- Použiť adresy URL: Informácie o verzii sú uvedené v adrese URL ako reťazec dopytu.
- Použite vlastné hlavičky požiadaviek: Informácie o verzii pre váš radič sú uvedené v hlavičke požiadavky, aby bolo potrebné vykonať akékoľvek zmeny v adrese URL.
- Použiť Prijať hlavičky: Prijať hlavičky všeobecne definuje typ média a kódovanie znakov. Informácie o verzii vášho webového rozhrania API môžete odovzdať prostredníctvom akceptovania hlavičiek bez toho, aby ste museli meniť adresu URL.
Správa verzií webového rozhrania API pomocou adries URL
Zvážte nasledujúce radiče webového rozhrania API, ktoré boli pomenovanéAuthorsV1Controller a AuthorsV2Controller resp.
verejná trieda AuthorsV1Controller: ApiController{
[HttpGet]
verejné IEnumerable GetAuthors ()
{
vrátiť nový reťazec [] {"Joydip Kanjilal", "Gerben Wierda"};
}
}
verejná trieda AuthorsV2Controller: ApiController
{
[HttpGet]
verejné IEnumerable GetAuthors ()
{
vrátiť nový reťazec [] {"Joydip Kanjilal, INDIA", "Gerben Wierda, Holandsko"};
}
}
Na zjednodušenie tejto ilustrácie som začlenil metódu s názvom GetAuthors () v každom ovládači. Zatiaľ čo GetAuthors () v AuthorsV1Controller vráti iba mená autorov, GetAuthors () v AuthorsV2Controller (nová verzia) vráti mená autorov spolu s názvami krajín, v ktorých majú autori bydlisko.
Nasledujúci úryvok kódu ukazuje, ako tieto dva ovládače používajú metódu Register WebApiConfig trieda.
config.Routes.MapHttpRoute (názov: "WebAPIV1",
routeTemplate: "api / v1 / {controller} / {id}",
predvolené hodnoty: new {controller = "AuthorsV1Controller", action = "GetAuthors", id = RouteParameter.Optional}
);
config.Routes.MapHttpRoute (
názov: "WebAPIV2",
routeTemplate: "api / v2 / {controller} / {id}",
predvolené hodnoty: new {controller = "AuthorsV2Controller", action = "GetAuthors", id = RouteParameter.Optional}
);
Teraz môžete vyvolať metódu webového API GetAuthors pomocou nasledujúcej adresy URL.
// localhost / WebAPI / api / v1 / Authors / GetAuthors
Verzovanie webového API pomocou hlavičky požiadavky
Verziu webového rozhrania API môžete implementovať aj pomocou hlavičky požiadavky. Aby ste to dosiahli, musíte implementovať vlastnú triedu, ktorá rozširuje DefaultHttpControllerSelector triedy, potom prepísať SelectController vo vlastnej triede. Všimnite si, že DefaultHttpControllerSelector trieda implementuje IHttpControllerSelector rozhranie.SelectController hovory GetControllerName interne a prijíma inštanciu HttpRequestMessage ako parameter.
Nasledujúci úryvok kódu ilustruje, ako môžete načítať informácie o verzii z hlavičky požiadavky.
súkromný reťazec GetControllerVersionFromRequestHeader (požiadavka HttpRequestMessage){
var acceptHeader = request.Headers.Accept;
const string headerName = "Verzia";
string controllerVersion = string.Empty;
if (request.Headers.Contains (headerName))
{
controllerVersion = "V" + request.Headers.GetValues (headerName) .First ();
}
návratový radičVerzia;
}
Verzovanie webového rozhrania API pomocou hlavičky prijatia
Nasledujúca metóda ukazuje, ako môžete načítať informácie o verzii pre vaše webové API z hlavičky prijatia. Metóda kontroluje typ MIME a príslušným spôsobom vracia informácie o verzii. Ak typ média nie je aplikácia / json, predvolená verzia sa vráti ako V1.
súkromný reťazec GetControllerVersionFromAcceptHeader (požiadavka HttpRequestMessage){
var acceptHeader = request.Headers.Accept;
string controllerVersion = string.Empty;
foreach (var mime v acceptHeader)
{
if (mime.MediaType.Equals ("application / json"))
{
NameValueHeaderValue verzia = mime.Parameters.FirstOrDefault (v => v.Name.Equals ("Verzia", StringComparison.OrdinalIgnoreCase));
controllerVersion = "V" + verzia.Value.ToString ();
návratový radičVerzia;
}
}
návrat "V1";
}
Webové rozhranie API môžete vyvolať z programu Fiddler odovzdaním hlavičky akceptovania, ako je uvedené nižšie.
Prijať: application / json; charset = utf-8; verzia = 2
Nasledujúci zoznam kódov ilustruje, ako môžete prepísať SelectController dynamicky zvoliť radič. Všimnite si ako GetControllerVersionFromRequestHeader bol použitý. Ak chcete získať verziu radiča z hlavičky prijatia, mali by ste využiť GetControllerVersionFromAcceptHeader namiesto toho.
verejné prepísanie HttpControllerDescriptor SelectController (požiadavka HttpRequestMessage){
skús
{
string controllerName = base.GetControllerName (požiadavka);
var controllers = GetControllerMapping ();
var routeData = request.GetRouteData ();
string controllerVersion = GetControllerVersionFromRequestHeader (požiadavka);
controllerName = String.Format ("{0} {1}", controllerName, controllerVersion);
HttpControllerDescriptor controllerDescriptor;
if (! controllers.TryGetValue (controllerName, out controllerDescriptor))
{
string message = "Nenašiel sa žiadny prostriedok HTTP, ktorý by zodpovedal zadanému identifikátoru URI požiadavky {0}";
hodiť novú HttpResponseException (request.CreateErrorResponse (System.Net.HttpStatusCode.NotFound, String.Format (message, request.RequestUri)));
}
návratový ovládač Deskriptor;
}
úlovok (výnimka okrem)
{
hodiť novú HttpResponseException (request.CreateErrorResponse (System.Net.HttpStatusCode.NotFound, String.Format (ex.Message, request.RequestUri)));
}
}
Nasledujúci riadok by ste mali pridať do metódy Register triedy WebApiConfig, aby ste poskytli podporu pre výber radiča za behu.
config.Services.Replace (typeof (IHttpControllerSelector), nový ControllerSelector ((config)));
Teraz môžete použiť program Fiddler na otestovanie svojho webového rozhrania API - použite kartu skladateľa programu Fiddler a podľa potreby uveďte informácie o adrese URL a verzii. Ak chcete vyvolať verziu 2 vášho radiča webového API, mali by ste to uviesť Verzia: 2 pri vytváraní informácií o hlavičke požiadavky na karte Skladateľ v nástroji Fiddler.
