Как да версия на вашия уеб API

Винаги трябва да версия на вашия уеб API, като същевременно запазвате колкото се може повече от един и същ URI. Представете си ситуация, в която имате уеб API, който работи и се използва от потребителите. Сега да предположим, че имате нужда от повече функционалност в уеб API, но все пак трябва да поддържате съществуващата функционалност непокътната. Може да имате няколко потребители, които все още се нуждаят от стария API, докато други ще се нуждаят от версия с нови или разширени функции. Точно тук на помощ идва версирането на уеб API.

Можете да версия на вашия уеб API по един от следните начини:

  1. Използване на URL адреси: Информацията за версията е посочена в URL адреса като низ за заявка.
  2. Използвайте персонализирани заглавки на заявки: Информацията за версията за вашия контролер е посочена в заглавката на заявката, без необходимостта от промени в URL адреса.
  3. Използвайте Accept Headers: Accept headers обикновено определят типа носител и кодирането на символи. Можете да предадете информация за версията за вашия уеб API чрез приемане на заглавки, без да се налага да променяте URL адреса.

Версиониране на уеб API с използване на URL адреси

Обмислете следните контролери на Web API, които са били именувани  AuthorsV1Controllerи AuthorsV2Controllerсъответно.

публичен клас AuthorsV1Controller: ApiController

    {

        [HttpGet]

        обществени IEnumerable GetAuthors ()

        {

          връщане на нов низ [] {"Joydip Kanjilal", "Gerben Wierda"};

        }

    }

публичен клас AuthorsV2Controller: ApiController

    {

        [HttpGet]

        обществени IEnumerable GetAuthors ()

        {

            връщане на нов низ [] {"Joydip Kanjilal, ИНДИЯ", "Gerben Wierda, Холандия"};

        }

    }

За да опростя тази илюстрация, съм включил метод, посочен GetAuthors()във всеки контролер. Докато GetAuthors()in AuthorsV1Controllerвръща само имената на авторите, GetAuthors()в AuthorsV2Controller(новата версия) връща имената на авторите заедно с имената на държавите, в които авторите пребивават.

Следният кодов фрагмент показва как двата контролера използват метода Register на WebApiConfigкласа.

config.Routes.MapHttpRoute (

                име: "WebAPIV1",

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

                по подразбиране: нов {controller = "AuthorsV1Controller", action = "GetAuthors", id = RouteParameter.O optional}

            );

config.Routes.MapHttpRoute (

                име: "WebAPIV2",

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

                по подразбиране: нов {controller = "AuthorsV2Controller", action = "GetAuthors", id = RouteParameter.O optional}

            );

Вече можете да извикате метода на Web API, GetAuthorsкато използвате следния URL адрес.

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

Версиониране на уеб API с помощта на заглавката на заявката

Можете също така да внедрите версирането на уеб API, като използвате заглавката на заявката. За да постигнете това, трябва да внедрите персонализиран клас, който разширява DefaultHttpControllerSelectorкласа, след което да замените SelectControllerв своя потребителски клас. Имайте предвид, че DefaultHttpControllerSelectorкласът реализира IHttpControllerSelectorинтерфейса. SelectControllerизвиква GetControllerNameвътрешно и приема екземпляр на HttpRequestMessageкато параметър.

Следният кодов фрагмент илюстрира как можете да извлечете информация за версията от заглавката на заявката.

частен низ GetControllerVersionFromRequestHeader (HttpRequestMessage заявка)

        {

            var acceptHeader = request.Headers.Accept;

            const string headerName = "Версия";

            низ controllerVersion = string.Empty;

            if (request.Headers.Contains (headerName))

            {

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

            }

            return controllerVersion;

        }

Версия на уеб API с помощта на заглавката за приемане

Следващият метод показва как можете да извлечете информация за версията за вашия уеб API от заглавката за приемане. Методът проверява типа MIME и връща информацията за версията по подходящ начин. Ако типът носител не е application/json, версията по подразбиране се връща като 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), нов ControllerSelector ((config)));

Вече можете да използвате Fiddler, за да тествате вашия уеб API - използвайте раздела за композиране на Fiddler и предоставете информация за URL и версия, както е подходящо. Ако искате да бъде извикана версия 2 на вашия контролер на уеб API, трябва да посочите Version: 2при съставянето на информацията за заглавката на заявката в раздела Композитор във Fiddler.