فرض کنید امروز یک API را برای استفاده عموم ارائه میدهید. آیا با یک breaking change در منابع شما که باعث تغییر در داده‌های ورودی یا خروجی API شود، باید استفاده کنندگان این API در سیستمی که از آن استفاده کرده‌اند، تغییراتی را اعمال کنند یا خیر؟ جواب خیر میباشد؛ اصلی‌ترین استفاده از API Versioning دقیقا برای این منظور است که بدون نگرانی از توسعه‌های بعدی، از ورژن‌های قدیمی API بتوانیم استفاده کنیم.
در این مقاله با روش‌های مختلف ورژن بندی API آشنا خواهید شد.
سه روش اصلی زیر را میتوان برای این منظور در نظر گرفت:
- URI-based versioning
- Header-based versioning
- Media type-based versioning
پیاده سازی URI-based versioning
حداقل به 3 طریق میتوان این مکانیسم را پیاده کرد:
راه حل اول: اگر از Attribute Routing استفاده نمی‌کنید، با تغییر جزئی در تعاریف مسیریابی خود میتوانید به نتیجه مورد نظر برسید. برای ادامه کار دو ویوومدل و دو کنترلر را که هر کدام مربوط به ورژن خاصی از API ما هستند، پیاده سازی میکنیم:
public class ItemViewModel
{
public int Id { get; set; }
public string Name { get; set; }
public string Country { get; set; }
}
public class ItemV2ViewModel : ItemViewModel
{
public double Price { get; set; }
} ItemViewModel مربوط به ورژن 1 میباشد.
public class ItemsController : ApiController
{
[ResponseType(typeof(ItemViewModel))]
public IHttpActionResult Get(int id)
{
var viewModel = new ItemViewModel { Id = id, Name = "PS4", Country = "Japan" };
return Ok(viewModel);
}
}
public class ItemsV2Controller : ApiController
{
[ResponseType(typeof(ItemV2ViewModel))]
public IHttpActionResult Get(int id)
{
var viewModel = new ItemV2ViewModel { Id = id, Name = "Xbox One", Country = "USA", Price = 529.99 };
return Ok(viewModel);
}
} ItemsController مربوط به ورژن 1 میباشد.
اگر قرار باشد از مسیرهای متمرکز استفاده کنیم، کافی است که تغییرات زیر را اعمال کنیم:
config.Routes.MapHttpRoute("ItemsV2", "api/v2/items/{id}", new
{
controller = "ItemsV2",
id = RouteParameter.Optional
});
config.Routes.MapHttpRoute("Items", "api/items/{id}", new
{
controller = "Items",
id = RouteParameter.Optional
});
config.Routes.MapHttpRoute(
name: "DefaultApi",
routeTemplate: "api/{controller}/{id}",
defaults: new { id = RouteParameter.Optional }
); در کد بالا به صراحت برای تک تک کنترلرها مسیریابی متناسب با ورژنی که آن را پشتیبانی میکند، معرفی کرده‌ایم.
نکته: این تنظیمات خاص باید قبل از تنظیمات پیش فرض قرار گیرند.
روش بالا به خوبی کار خواهد کرد ولی آنچنان مطلوب نمیباشد. به همین دلیل یک مسیریابی عمومی و کلی را در نظر میگیریم که شامل ورژن مورد نظر، در قالب یک پارامتر میباشد. در روش جایگزین باید به شکل زیر عمل کنید:
config.Routes.MapHttpRoute(
"defaultVersioned",
"api/v{version}/{controller}/{id}",
new { id = RouteParameter.Optional }, new { version = @"\d+" });
config.Routes.MapHttpRoute(
"DefaultApi",
"api/{controller}/{id}",
new { id = RouteParameter.Optional }
); با این تنظیمات فعلا به مسیریابی ورژن بندی شده‌ای دست نیافته‌ایم. زیرا فعلا به هیچ طریق به Web API اشاره نکرده‌ایم که به چه صورت از این پارامتر version برای پیدا کردن کنترلر ورژن بندی شده استفاده کند و به همین دلیل این دو مسیریابی نوشته شده در عمل نتیجه یکسانی را خواهند داشت. برای رفع مشکل مطرح شده باید فرآیند پیش فرض انتخاب کنترلر را کمی شخصی سازی کنیم.
IHttpControllerSelector مسئول پیدا کردن کنترلر مربوطه با توجه به درخواست رسیده میباشد. شکل زیر مربوط است به مراحل ساخت کنترلر بر اساس درخواست رسیده:
به جای پیاده سازی مستقیم این اینترفیس، از پیاده سازی کننده پیش فرض موجود (DefaultHttpControllerSelector) اسفتاده کرده و HttpControllerSelector جدید ما از آن ارث بری خواهد کرد.
public class VersionFinder
{
private static bool NeedsUriVersioning(HttpRequestMessage request, out string version)
{
var routeData = request.GetRouteData();
if (routeData != null)
{
object versionFromRoute;
if (routeData.Values.TryGetValue(nameof(version), out versionFromRoute))
{
version = versionFromRoute as string;
if (!string.IsNullOrWhiteSpace(version))
{
return true;
}
}
}
version = null;
return false;
}
private static int VersionToInt(string versionString)
{
int version;
if (string.IsNullOrEmpty(versionString) || !int.TryParse(versionString, out version))
return 0;
return version;
}
public static int GetVersionFromRequest(HttpRequestMessage request)
{
string version;
return NeedsUriVersioning(request, out version) ? VersionToInt(version) : 0;
}
} کلاس VersionFinder برای یافتن ورژن رسیده در درخواست جاری مورد استفاده قرار خواهد گرفت. با استفاده از متد NeedsUriVersioning بررسی صورت می‌گیرد که آیا در این درخواست پارامتری به نام version وجود دارد یا خیر که درصورت موجود بودن، مقدار آن واکشی شده و درون پارامتر out قرار می‌گیرد. در متد GetVersionFromRequest بررسی میشود که اگر خروجی متد NeedsUriVersioning برابر با true باشد، با استفاده از متد VersionToInt مقدار به دست آمده را به int تبدیل کند.
public class VersionAwareControllerSelector : DefaultHttpControllerSelector
{
public VersionAwareControllerSelector(HttpConfiguration configuration) : base(configuration) { }
public override string GetControllerName(HttpRequestMessage request)
{
var controllerName = base.GetControllerName(request);
var version = VersionFinder.GetVersionFromRequest(request);
return version > 0 ? GetVersionedControllerName(request, controllerName, version) : controllerName;
}
private string GetVersionedControllerName(HttpRequestMessage request, string baseControllerName,
int version)
{
var versionControllerName = $"{baseControllerName}v{version}";
HttpControllerDescriptor descriptor;
if (GetControllerMapping().TryGetValue(versionControllerName, out descriptor))
{
return versionControllerName;
}
throw new HttpResponseException(request.CreateErrorResponse(
HttpStatusCode.NotFound,
$"No HTTP resource was found that matches the URI {request.RequestUri} and version number {version}"));
}
} متد GetControllerName وظیفه بازگشت دادن نام کنترلر را برعهده دارد. ما نیز با لغو رفتار پیش فرض این متد و تهیه نام ورژن بندی شده کنترلر و معرفی این پیاده سازی از IHttpControllerSelector به شکل زیر میتوانیم به Web API بگوییم که به چه صورت از پارامتر version موجود در درخواست استفاده کند.
config.Services.Replace(typeof(IHttpControllerSelector), new VersionAwareControllerSelector(config));
حال با اجرای برنامه به نتیجه زیر خواهیم رسید:
راه حل دوم: برای زمانیکه Attribute Routing مورد استفاده شما است میتوان به راحتی با تعریف قالب‌های مناسب مسیریابی، API ورژن بندی شده را ارائه دهید.
[RoutePrefix("api/v1/Items")]
public class ItemsController : ApiController
{
[ResponseType(typeof(ItemViewModel))]
[Route("{id:int}")]
public IHttpActionResult Get(int id)
{
var viewModel = new ItemViewModel { Id = id, Name = "PS4", Country = "Japan" };
return Ok(viewModel);
}
}
[RoutePrefix("api/V2/Items")]
public class ItemsV2Controller : ApiController
{
[ResponseType(typeof(ItemV2ViewModel))]
[Route("{id:int}")]
public IHttpActionResult Get(int id)
{
var viewModel = new ItemV2ViewModel { Id = id, Name = "Xbox One", Country = "USA", Price = 529.99 };
return Ok(viewModel);
}
} اگر توجه کرده باشید در مثال ما، نام‌های کنترلرها متفاوت از هم میباشند. اگر بجای در نظر گرفتن نام‌های مختلف برای یک کنترلر در ورژن‌های مختلف، آن را با یک نام یکسان درون namespaceهای مختلف احاطه کنیم یا حتی آنها را درون Class Libraryهای جدا نگهداری کنیم، به مشکل "یافت شدن چندین کنترلر که با درخواست جاری مطابقت دارند" برخواهیم خورد. برای حل این موضوع به راه حل سوم توجه کنید.
راه حل سوم: استفاده از یک NamespaceControllerSelector که پیاده سازی دیگری از اینترفیس IHttpControllerSelector میباشد. فرض بر این است که قالب پروژه به شکل زیر میباشد:
کار با پیاده سازی اینترفیس IHttpRouteConstraint آغاز میشود:
public class VersionConstraint : IHttpRouteConstraint
{
public VersionConstraint(string allowedVersion)
{
AllowedVersion = allowedVersion.ToLowerInvariant();
}
public string AllowedVersion { get; private set; }
public bool Match(HttpRequestMessage request, IHttpRoute route, string parameterName,
IDictionary<string, object> values, HttpRouteDirection routeDirection)
{
object value;
if (values.TryGetValue(parameterName, out value) && value != null)
{
return AllowedVersion.Equals(value.ToString().ToLowerInvariant());
}
return false;
}
} کلاس بالا در واقع برای اعمال محدودیت خاصی که در ادامه توضیح داده میشود، پیاده سازی شده است.
متد Match آن وظیفه چک کردن برابری مقدار کلید parameterName موجود در درخواست را با مقدار allowedVersion ای که API از آن پشتیبانی میکند، برعهده دارد. با استفاده از این Constraint مشخص کرده‌ایم که دقیقا چه زمانی باید Route نوشته شده انتخاب شود.
به روش استفاده از این Constraint توجه کنید:
namespace UriBasedVersioning.Namespace.Controllers.V1
{
using Models.V1;
RoutePrefix("api/{version:VersionConstraint(v1)}/items")]
public class ItemsController : ApiController
{
[ResponseType(typeof(ItemViewModel))]
[Route("{id}")]
public IHttpActionResult Get(int id)
{
var viewModel = new ItemViewModel { Id = id, Name = "PS4", Country = "Japan" };
return Ok(viewModel);
}
}
}
namespace UriBasedVersioning.Namespace.Controllers.V2
{
using Models.V2;
RoutePrefix("api/{version:VersionConstraint(v2)}/items")]
public class ItemsController : ApiController
{
[ResponseType(typeof(ItemViewModel))]
[Route("{id}")]
public IHttpActionResult Get(int id)
{
var viewModel = new ItemViewModel { Id = id, Name = "Xbox One", Country = "USA", Price = 529.99 };
return Ok(viewModel);
}
}
} با توجه به کد بالا میتوان دلیل استفاده از VersionConstraint را هم درک کرد؛ از آنجایی که ما دو Route شبیه به هم داریم، لذا باید مشخص کنیم که در چه شرایطی و کدام یک از این Routeها انتخاب شود. خوب، اگر برنامه را اجرا کرده و یکی از APIهای بالا را تست کنید، با خطا مواجه خواهید شد؛ زیرا فعلا این Constraint به سیستم Web API معرفی نشده است. تنظیمات زیر را انجام دهید:
var constraintsResolver = new DefaultInlineConstraintResolver();
constraintsResolver.ConstraintMap.Add(nameof(VersionConstraint), typeof
(VersionConstraint));
config.MapHttpAttributeRoutes(constraintsResolver); مرحله بعدی کار، پیاده سازی IHttpControllerSelector میباشد:
public class NamespaceControllerSelector : IHttpControllerSelector
{
private readonly HttpConfiguration _configuration;
private readonly Lazy<Dictionary<string, HttpControllerDescriptor>> _controllers;
public NamespaceControllerSelector(HttpConfiguration config)
{
_configuration = config;
_controllers = new Lazy<Dictionary<string,
HttpControllerDescriptor>>(InitializeControllerDictionary);
}
public HttpControllerDescriptor SelectController(HttpRequestMessage request)
{
var routeData = request.GetRouteData();
if (routeData == null)
{
throw new HttpResponseException(HttpStatusCode.NotFound);
}
var controllerName = GetControllerName(routeData);
if (controllerName == null)
{
throw new HttpResponseException(HttpStatusCode.NotFound);
}
var version = GetVersion(routeData);
if (version == null)
{
throw new HttpResponseException(HttpStatusCode.NotFound);
}
var controllerKey = string.Format(CultureInfo.InvariantCulture, "{0}.{1}",
version, controllerName);
HttpControllerDescriptor controllerDescriptor;
if (_controllers.Value.TryGetValue(controllerKey, out controllerDescriptor))
{
return controllerDescriptor;
}
throw new HttpResponseException(HttpStatusCode.NotFound);
}
public IDictionary<string, HttpControllerDescriptor> GetControllerMapping()
{
return _controllers.Value;
}
private Dictionary<string, HttpControllerDescriptor> InitializeControllerDictionary()
{
var dictionary = new Dictionary<string,
HttpControllerDescriptor>(StringComparer.OrdinalIgnoreCase);
var assembliesResolver = _configuration.Services.GetAssembliesResolver();
var controllersResolver = _configuration.Services.GetHttpControllerTypeResolver();
var controllerTypes = controllersResolver.GetControllerTypes(assembliesResolver);
foreach (var controllerType in controllerTypes)
{
var segments = controllerType.Namespace.Split(Type.Delimiter);
var controllerName =
controllerType.Name.Remove(controllerType.Name.Length -
DefaultHttpControllerSelector.ControllerSuffix.Length);
var controllerKey = string.Format(CultureInfo.InvariantCulture, "{0}.{1}",
segments[segments.Length - 1], controllerName);
if (!dictionary.Keys.Contains(controllerKey))
{
dictionary[controllerKey] = new HttpControllerDescriptor(_configuration,
controllerType.Name,
controllerType);
}
}
return dictionary;
}
private static T GetRouteVariable<T>(IHttpRouteData routeData, string name)
{
object result;
if (routeData.Values.TryGetValue(name, out result))
{
return (T)result;
}
return default(T);
}
private static string GetControllerName(IHttpRouteData routeData)
{
var subroute = routeData.GetSubRoutes().FirstOrDefault();
var dataTokenValue = subroute?.Route.DataTokens.First().Value;
var controllerName =
((HttpActionDescriptor[])dataTokenValue)?.First().ControllerDescriptor.ControllerName.Replace("Controller", string.Empty);
return controllerName;
}
private static string GetVersion(IHttpRouteData routeData)
{
var subRouteData = routeData.GetSubRoutes().FirstOrDefault();
return subRouteData == null ? null : GetRouteVariable<string>(subRouteData, "version");
}
} سورس اصلی کلاس بالا از این آدرس قابل دریافت است. در تکه کد بالا بخشی که مربوط به چک کردن تکراری بودن آدرس میباشد، برای ساده سازی کار حذف شده است. ولی نکته‌ی مربوط به SubRoutes که برای واکشی مقادیر پارامترهای مرتبط با Attribute Routing میباشد، اضافه شده است. روال کار به این صورت است که ابتدا RouteData موجود در درخواست را واکشی کرده و با استفاده از متدهای GetControllerName و GetVersion، پارامترهای controller و version را جستجو میکنیم. بعد با استفاده از مقادیر به دست آمده، controllerKey را تشکیل داده و درون کنترلر‌های موجود در برنامه به دنبال کنترلر مورد نظر خواهیم گشت.
کارکرد متد InitializeControllerDictionary :
همانطور که میدانید به صورت پیش‌فرض Web API توجهی به فضای نام مرتبط با کنترلرها ندارد. از طرفی برای پیاده سازی اینترفیس IHttpControllerSelector نیاز است متدی با امضای زیر را داشته باشیم:
public IDictionary<string, HttpControllerDescriptor> GetControllerMapping()
لذا در کلاس پیاده سازی شده، خصوصیتی به نام _controllers را که از به صورت Lazy و از نوع بازگشتی متد بالا میباشد، تعریف کرده‌ایم. متد InitializeControllerDictionary کار آماده سازی داده‌های مورد نیاز خصوصیت _controllers میباشد. به این صورت که تمام کنترلر‌های موجود در برنامه را واکشی کرده و این بار کلید‌های مربوط به دیکشنری را با استفاده از نام کنترلر و آخرین سگمنت فضای نام آن، تولید و درون دیکشنری مورد نظر ذخیره کرده‌ایم.
حال تنظیمات زیر را اعمال کنید:
public static class WebApiConfig
{
public static void Register(HttpConfiguration config)
{
var constraintsResolver = new DefaultInlineConstraintResolver();
constraintsResolver.ConstraintMap.Add(nameof(VersionConstraint), typeof
(VersionConstraint));
config.MapHttpAttributeRoutes(constraintsResolver);
config.Services.Replace(typeof(IHttpControllerSelector), new NamespaceControllerSelector(config));
}
} این بار برنامه را اجرا کرده و APIهای مورد نظر را تست کنید؛ بله بدون مشکل کار خواهد کرد.
نکته تکمیلی: سورس مذکور در سایت کدپلکس برای حالتی که از Centralized Routes استفاده میکنید آماده شده است. روش مذکور در این مقاله هم فقط قسمت Duplicate Routes آن را کم دارد که میتوانید اضافه کنید. پیاده سازی دیگری را از این راه حل هم میتوانید داشته باشید.
پیاده سازی Header-based versioning
در این روش کافی است هدری را برای دریافت ورژن API درخواستی مشخص کرده باشید. برای مثال هدری به نام api-version، که استفاده کننده از این طریق، ورژن درخواستی خود را اعلام میکند. همانطور که قبلا اشاره کردیم، با استفاده از Constraintها دست شما خیلی باز خواهد بود. برای مثال این بار به جای واکشی پارامتر version از RouteData، کد همان قسمت را برای واکشی آن از هدر درخواستی تغییر خواهیم داد:
public class HeaderVersionConstraint : IHttpRouteConstraint
{
private const string VersionHeaderName = "api-version";
public HeaderVersionConstraint(int allowedVersion)
{
AllowedVersion = allowedVersion;
}
public int AllowedVersion { get; }
public bool Match(HttpRequestMessage request, IHttpRoute route, string parameterName,
IDictionary<string, object> values,
HttpRouteDirection routeDirection)
{
if (!request.Headers.Contains(VersionHeaderName)) return false;
var version = request.Headers.GetValues(VersionHeaderName).FirstOrDefault();
return VersionToInt(version) == AllowedVersion;
}
private static int VersionToInt(string versionString)
{
int version;
if (string.IsNullOrEmpty(versionString) || !int.TryParse(versionString, out version))
return 0;
return version;
}
} این بار در متد Match، به دنبال هدر خاصی به نام api-version می‌گردیم و مقدار آن را با AllowdVersion مقایسه میکنیم تا مشخص کنیم که آیا این Route نوشته شده برای ادامه کار واکشی کنترلر مورد نظر استفاده شود یا خیر. در ادامه یک RouteFactoryAttribute شخصی سازی شده را به منظور معرفی این محدودیت تعریف شده، در نظر میگیریم:
public sealed class HeaderVersionedRouteAttribute : RouteFactoryAttribute
{
public HeaderVersionedRouteAttribute(string template) : base(template)
{
Order = -1;
}
public int Version { get; set; }
public override IDictionary<string, object> Constraints => new HttpRouteValueDictionary
{
{"", new HeaderVersionConstraint(Version)}
};
} با استفاده از خصوصیت Constraints، توانستیم محدودیت پیاده سازی شده خود را به سیستم مسیریابی معرفی کنیم. توجه داشته باشید که این بار هیچ پارامتری در Uri تحت عنوان version را نداریم و از این جهت به صراحت کلیدی برای آن مشخص نکرده ایم ({"", new HeaderVersionConstraint(Version)} ).
کنترلر‌های ما به شکل زیر خواهند بود:
[RoutePrefix("api/items")]
public class ItemsController : ApiController
{
[ResponseType(typeof(ItemViewModel))]
[HeaderVersionedRoute("{id}", Version = 1)]
public IHttpActionResult Get(int id)
{
var viewModel = new ItemViewModel { Id = id, Name = "PS4", Country = "Japan" };
return Ok(viewModel);
}
}
[RoutePrefix("api/items")]
public class ItemsV2Controller : ApiController
{
[ResponseType(typeof(ItemV2ViewModel))]
[HeaderVersionedRoute("{id}", Version = 2)]
public IHttpActionResult Get(int id)
{
var viewModel = new ItemV2ViewModel { Id = id, Name = "Xbox One", Country = "USA", Price = 529.99 };
return Ok(viewModel);
}
}
این بار از VersionedRoute برای اعمال مسیر یابی Attribute-based استفاده کرده ایم و به صراحت ورژن هر کدام را با استفاده از خصوصیت Version آن مشخص کرده‌ایم. نتیجه:
پیاده سازی Media type-based versioning
قرار است ورژن API مورد نظر را که استفاده کننده درخواست میدهد، از دل درخواست‌هایی به فرم زیر واکشی کنیم:
GET /api/Items HTTP 1.1
Accept: application/vnd.mediatype.versioning-v1+json
GET /api/Items HTTP 1.1
Accept: application/vnd.mediatype.versioning-v2+json
در این روش دست ما کمی بازتر است چرا که میتوانیم بر اساس فرمت درخواستی نیز تصمیماتی را برای ارائه ورژن خاصی از API داشته باشیم. روال کار شبیه به روش قبلی با پیاده سازی یک Constraint و یک RouteFactoryAttribute انجام خواهد گرفت.
public class MediaTypeVersionConstraint : IHttpRouteConstraint
{
private const string VersionMediaType = "vnd.mediatype.versioning";
public MediaTypeVersionConstraint(int allowedVersion)
{
AllowedVersion = allowedVersion;
}
public int AllowedVersion { get; }
public bool Match(HttpRequestMessage request, IHttpRoute route, string parameterName, IDictionary<string, object> values,
HttpRouteDirection routeDirection)
{
if (!request.Headers.Accept.Any()) return false;
var acceptHeaderVersion =
request.Headers.Accept.FirstOrDefault(x => x.MediaType.Contains(VersionMediaType));
//Accept: application/vnd.mediatype.versioning-v1+json
if (acceptHeaderVersion == null || !acceptHeaderVersion.MediaType.Contains("-v") ||
!acceptHeaderVersion.MediaType.Contains("+"))
return false;
var version = acceptHeaderVersion.MediaType.Between("-v", "+");
return VersionToInt(version)==AllowedVersion;
}
}
در متد Match کلاس بالا به دنبال مدیا تایپ مشخصی هستیم که با هدر Accept برای ما ارسال میشود. برای آشنایی با فرمت ارسال Media Typeها میتوانید به
اینجا مراجعه کنید. کاری که در اینجا انجام شده‌است، یافتن ورژن ارسالی توسط استفاده کننده میباشد که آن را با فرمت خاصی که نشان داده شد و مابین (v-) و (+) قرار داده، ارسال میشود. ادامه کار به مانند روش Header-based میباشد و از مطرح کردن آن در مقاله خودداری میکنیم.
نتیجه به شکل زیر خواهد بود:
کدهای کامل این قسمت را از اینجا میتوانید دریافت کنید.
در قسمت ریلیز میتوانید ببینید که ریلیز توسط ربات گیتهاب ایجاد شده‌است:
