Kako verzirati svoj web API

Uvijek biste trebali verzijati svoj Web API, istovremeno zadržavajući što više istog URI-a. Zamislite situaciju u kojoj imate web API koji je pokrenut i pokrenut u proizvodnji i koji korisnici konzumiraju. Sada pretpostavimo da vam treba više funkcionalnosti u web API-ju, ali da postojeću funkcionalnost morate zadržati netaknutom. Možda imate nekoliko korisnika kojima još uvijek treba stari API, dok će drugima trebati verzija s novim ili proširenim značajkama. Upravo tu u pomoć dolazi izrada verzija web API-ja.

Svoj web API možete verzirati na jedan od sljedećih načina:

  1. Upotrijebi URL-ove: Podaci o inačici navedeni su u URL-u kao niz upita.
  2. Koristite prilagođena zaglavlja zahtjeva: Podaci o verziji vašeg kontrolera navedeni su u zaglavlju zahtjeva, osim potrebe za bilo kakvim promjenama u URL-u.
  3. Koristite Prihvati zaglavlja: Prihvati zaglavlja obično definiraju vrstu medija i kodiranje znakova. Informacije o verziji za svoj web API možete proslijediti putem zaglavlja prihvaćanja bez potrebe za promjenom URL-a.

Izrada verzija web API-ja pomoću URL-ova

Razmotrite sljedeće Web API kontrolera, koji se zove  AuthorsV1Controlleri AuthorsV2Controllerodnosno.

javna klasa AuthorsV1Controller: ApiController

    {

        [HttpGet]

        javni IEnumerable GetAuthors ()

        {

          vrati novi niz [] {"Joydip Kanjilal", "Gerben Wierda"};

        }

    }

javna klasa AuthorsV2Controller: ApiController

    {

        [HttpGet]

        javni IEnumerable GetAuthors ()

        {

            vrati novi niz [] {"Joydip Kanjilal, INDIJA", "Gerben Wierda, Nizozemska"};

        }

    }

Da bih pojednostavio ovu ilustraciju, ugradio sam metodu imenovanu GetAuthors()u svaki kontroler. Dok GetAuthors()in AuthorsV1Controllervraća samo imena autora, GetAuthors()u AuthorsV2Controller(nova verzija) vraća imena autora zajedno s imenima zemalja u kojima autori borave.

Sljedeći isječak koda pokazuje kako dva kontrolora koriste metodu Registriraj WebApiConfigklase.

config.Routes.MapHttpRoute (

                ime: "WebAPIV1",

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

                zadane vrijednosti: novo {controller = "AuthorsV1Controller", action = "GetAuthors", id = RouteParameter.Optional}

            );

config.Routes.MapHttpRoute (

                ime: "WebAPIV2",

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

                zadane vrijednosti: novo {controller = "AuthorsV2Controller", action = "GetAuthors", id = RouteParameter.O optional}

            );

Sada se možete pozvati na metodu Web API GetAuthorspomoću sljedećeg URL-a.

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

Izrada verzija web API-ja pomoću zaglavlja zahtjeva

Također možete implementirati izradu verzija web API-ja pomoću zaglavlja zahtjeva. Da biste to postigli, morate implementirati prilagođenu klasu koja proširuje DefaultHttpControllerSelectorklasu, a zatim poništiti SelectControlleru svojoj prilagođenoj klasi. Imajte na umu da DefaultHttpControllerSelectorklasa implementira IHttpControllerSelectorsučelje. SelectControllerpoziva GetControllerNameinterno i prihvaća instancu HttpRequestMessagekao parametar.

Sljedeći isječak koda ilustrira kako možete dobiti informacije o verziji iz zaglavlja zahtjeva.

privatni niz GetControllerVersionFromRequestHeader (zahtjev za HttpRequestMessage)

        {

            var acceptHeader = request.Headers.Accept;

            const string headerName = "Verzija";

            string controllerVersion = string.Empty;

            if (request.Headers.Contens (headerName))

            {

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

            }

            povratak controllerVersion;

        }

Izrada verzija web API-ja pomoću zaglavlja accept

Sljedeća metoda pokazuje kako možete dobiti informacije o verziji za svoj web API iz zaglavlja accept. Metoda provjerava MIME tip i prikladno vraća podatke o verziji. Ako vrsta medija nije application/json, zadana verzija vraća se kao V1.

private string GetControllerVersionFromAcceptHeader(HttpRequestMessage request)

        {

            var acceptHeader = request.Headers.Accept;

            string controllerVersion = string.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" + version.Value.ToString();

                    return controllerVersion;

                }

            }

            return "V1";

        }

You can invoke your Web API from Fiddler by passing the accept header as shown below.

Accept: application/json; charset=utf-8;version=2

The following code listing illustrates how you can override SelectController to select a controller dynamically. Note how GetControllerVersionFromRequestHeader has been used. If you would like to retrieve the controller version from the accept header, you should leverage GetControllerVersionFromAcceptHeader instead.

public override HttpControllerDescriptor SelectController(HttpRequestMessage request)

        {

            try

            {

                string controllerName = base.GetControllerName(request);

                var controllers = GetControllerMapping();

                var routeData = request.GetRouteData();

                string controllerVersion = GetControllerVersionFromRequestHeader(request);             

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

                HttpControllerDescriptor controllerDescriptor;

                if (!controllers.TryGetValue(controllerName, out controllerDescriptor))

                {

                    string message = "No HTTP resource was found that matches the specified request URI {0}";

                    throw new HttpResponseException(request.CreateErrorResponse(System.Net.HttpStatusCode.NotFound, String.Format(message, request.RequestUri)));

                }

                return controllerDescriptor;

            }

            catch (Exception ex)

            {

                throw new HttpResponseException(request.CreateErrorResponse(System.Net.HttpStatusCode.NotFound, String.Format(ex.Message, request.RequestUri)));

            }

        }

You should add the following line in the Register method of the WebApiConfig class to provide support for controller selection at runtime.

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

Sada možete koristiti Fiddler za testiranje svog web API-ja - upotrijebite kompozitorsku karticu Fiddlera i pružite informacije o URL-u i verziji prema potrebi. Ako želite da se poziva verzija 2 vašeg web API kontrolera, trebali biste navesti Version: 2prilikom sastavljanja podataka zaglavlja zahtjeva na kartici Sastavljač u Fiddleru.