Винаги трябва да версия на вашия уеб API, като същевременно запазвате колкото се може повече от един и същ URI. Представете си ситуация, в която имате уеб API, който работи и се използва от потребителите. Сега да предположим, че имате нужда от повече функционалност в уеб API, но все пак трябва да поддържате съществуващата функционалност непокътната. Може да имате няколко потребители, които все още се нуждаят от стария API, докато други ще се нуждаят от версия с нови или разширени функции. Точно тук на помощ идва версирането на уеб API.
Можете да версия на вашия уеб API по един от следните начини:
- Използване на URL адреси: Информацията за версията е посочена в URL адреса като низ за заявка.
- Използвайте персонализирани заглавки на заявки: Информацията за версията за вашия контролер е посочена в заглавката на заявката, без необходимостта от промени в URL адреса.
- Използвайте 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.