Programavimas

Kaip versijoti savo žiniatinklio API

Visada turėtumėte versijos savo žiniatinklio API versiją, tuo pačiu išlaikydami kuo daugiau to paties URI. Įsivaizduokite situaciją, kai turite žiniatinklio API, kuri yra sukurta ir veikia gamyboje ir kurią vartoja vartotojai. Dabar tarkime, kad jums reikia daugiau funkcijų žiniatinklio API, tačiau esamos funkcijos turi būti nepažeistos. Galbūt turite kelis vartotojus, kuriems vis dar reikalinga senoji API, o kitiems reikės versijos su naujomis arba išplėstomis funkcijomis. Būtent čia gelbsti žiniatinklio API versijos.

Galite versijinti savo žiniatinklio API vienu iš šių būdų:

  1. Naudoti URL: versijos informacija nurodoma URL kaip užklausos eilutė.
  2. Naudokite pasirinktines užklausų antraštes: valdiklio versijos informacija nurodoma užklausos antraštėje, kad nereikia keisti jokių URL.
  3. Naudokite „Accept Headers“: „Accept Headers“ paprastai apibrėžia laikmenos tipą ir simbolių kodavimą. Informaciją apie savo žiniatinklio API galite perduoti per priimdami antraštes, nekeisdami URL.

Versija žiniatinklio API naudojant URL

Apsvarstykite šiuos žiniatinklio API valdiklius, kurie buvo pavadintiAutoriaiV1Kontrolierius ir AutoriaiV2Kontrolierius atitinkamai.

public class AuthorsV1Controller: ApiController

    {

[HttpGet]

public ISuskaičiuojami „GetAuthors“ ()

        {

grąžinti naują eilutę [] {"Joydip Kanjilal", "Gerben Wierda"};

        }

    }

public class AuthorsV2Controller: ApiController

    {

[HttpGet]

public ISuskaičiuojami „GetAuthors“ ()

        {

grąžinti naują eilutę [] {"Joydip Kanjilal, INDIJA", "Gerben Wierda, Nyderlandai"};

        }

    }

Norėdami supaprastinti šią iliustraciją, įtraukiau pavadintą metodą „GetAuthors“ () kiekviename valdiklyje. Nors „GetAuthors“ () į AutoriaiV1Kontrolierius grąžina tik autorių vardus, „GetAuthors“ () į AutoriaiV2Kontrolierius (nauja versija) pateikia autorių vardus kartu su šalių, kuriose autoriai gyvena, pavadinimais.

Šis kodo fragmentas parodo, kaip du valdikliai naudoja registro metodą „WebApiConfig“ klasė.

config.Routes.MapHttpRoute (

pavadinimas: "WebAPIV1",

routeTemplate: "api / v1 / {controller} / {id}",

numatytieji parametrai: new {controller = "AuthorsV1Controller", action = "GetAuthors", id = RouteParameter.Optional}

            );

config.Routes.MapHttpRoute (

pavadinimas: „WebAPIV2“,

routeTemplate: "api / v2 / {controller} / {id}",

numatytieji parametrai: new {controller = "AuthorsV2Controller", action = "GetAuthors", id = RouteParameter.Optional}

            );

Dabar galite pasinaudoti žiniatinklio API metodu „GetAuthors“ naudojant šį URL.

// localhost / WebAPI / api / v1 / Authors / GetAuthors

Versijos žiniatinklio API naudojant užklausos antraštę

Taip pat galite įdiegti žiniatinklio API versijas naudodami užklausos antraštę. Norėdami tai pasiekti, turite įdiegti pasirinktinę klasę, kuri pratęsia DefaultHttpControllerSelector klasę, tada nepaisykite Pasirinkite valdiklį jūsų pasirinktoje klasėje. Atkreipkite dėmesį, kad DefaultHttpControllerSelector klasė įgyvendina „IHttpControllerSelector“ sąsaja.Pasirinkite valdiklį skambučių „GetControllerName“ viduje ir priima „HttpRequestMessage“ kaip parametrą.

Šis kodo fragmentas parodo, kaip galite gauti informacijos apie versiją iš užklausos antraštės.

privati ​​eilutė „GetControllerVersionFromRequestHeader“ („HttpRequestMessage“ užklausa)

        {

var acceptHeader = request.Headers.Accept;

const string headerName = "Versija";

string controllerVersion = eilutė. Tuščias;

jei (request.Headers.Contains (headerName))

            {

controllerVersion = "V" + request.Headers.GetValues ​​(headerName) .First ();

            }

grąžinimo valdiklisVersija;

        }

Versija „Web API“ naudojant antraštę „accept“

Šis metodas parodo, kaip galite gauti žiniatinklio API versijos informaciją iš antraštės „accept“. Metodas patikrina MIME tipą ir tinkamai pateikia informaciją apie versiją. Jei laikmenos tipas nėra paraiška / Json, numatytoji versija grąžinama kaip V1.

privati ​​eilutė „GetControllerVersionFromAcceptHeader“ („HttpRequestMessage“ užklausa)

        {

var acceptHeader = request.Headers.Accept;

string controllerVersion = eilutė. Tuščias;

foreach (var mime in acceptHeader)

            {

if („mime.MediaType.Equals“ („application / json“))

                {

NameValueHeaderValue version = mime.Parameters.FirstOrDefault (v => v.Name.Equals ("Versija", StringComparison.OrdinalIgnoreCase));

controllerVersion = "V" + versija.Value.ToString ();

grąžinimo valdiklisVersija;

                }

            }

grąžinti „V1“;

        }

Galite iškviesti savo žiniatinklio API iš „Fiddler“ perduodami antraštę „accept“, kaip parodyta žemiau.

Priimti: paraiška / json; simbolis = utf-8; versija = 2

Šis kodų sąrašas parodo, kaip galite nepaisyti Pasirinkite valdiklį dinamiškai pasirinkti valdiklį. Atkreipkite dėmesį, kaip „GetControllerVersionFromRequestHeader“ buvo panaudotas. Jei norite gauti valdiklio versiją iš „header“, turėtumėte pasinaudoti svertu „GetControllerVersionFromAcceptHeader“ vietoj to.

viešasis „HttpControllerDescriptor SelectController“ nepaisymas („HttpRequestMessage“ užklausa)

        {

bandyti

            {

string controllerName = base.GetControllerName (užklausa);

var kontrolieriai = GetControllerMapping ();

var routeData = request.GetRouteData ();

eilutė controllerVersion = GetControllerVersionFromRequestHeader (užklausa);

controllerName = String.Format ("{0} {1}", controllerName, controllerVersion);

HttpControllerDescriptor controllerDescriptor;

if (! kontrolleriai. TryGetValue (valdiklio pavadinimas, iš valdiklio aprašas)]

                {

string message = "Nerastas HTTP šaltinis, atitinkantis nurodytą užklausos URI {0}";

mesti naują HttpResponseException (request.CreateErrorResponse (System.Net.HttpStatusCode.NotFound, String.Format (pranešimas, request.RequestUri)));

                }

grąžinimo valdiklisDescriptor;

            }

sugavimas (ex išimtis)

            {

mesti naują HttpResponseException (request.CreateErrorResponse (System.Net.HttpStatusCode.NotFound, String.Format (pvz., Pranešimas, request.RequestUri)));

            }

        }

Turėtumėte įtraukti šią eilutę į „WebApiConfig“ klasės registravimo metodą, kad palaikytumėte valdiklį pasirinkdami vykdymo metu.

config.Services.Replace (typeof (IHttpControllerSelector), naujas ControllerSelector ((config)));

Dabar galite naudoti „Fiddler“, norėdami išbandyti savo žiniatinklio API - naudokite „Fiddler“ kompozitoriaus skirtuką ir, jei reikia, pateikite informaciją apie URL ir versiją. Jei norite, kad būtų naudojama jūsų žiniatinklio API valdiklio 2 versija, turėtumėte nurodyti Versija: 2 sudarant užklausos antraštės informaciją „Fiddler“ skirtuke Kompozitorius.