زمانی که یک API عمومی می شود، کلاینت های مختلفی از آن استفاده می کنند و بخشی از Business آنها وابسته به آن API می شود. با توسعه ی Business و یا تغییر نیازمندی ها، نیاز به تغییرات در API حس می شود. اما این تغییرات نباید به گونه ای باشد تا در عملکرد API خللی وارد شود. در اینجا بحث Versioning کردن API مطرح می شود. در این صورت هم کلاینت های قدیمی می توانند از API استفاده کنند و هم کلاینت های جدید.
به چند طریق می توان از Web API Versioning استفاده کرد:
- URL Routing
- Query String
- HTTP Header
- Accept Header
- Media Type
که روش های URL Routing, QueryString, HTTP Header از بقیه ی روش ها معروف تر هستند.
اولین قدم نصب یک NuGet به نام Microsoft.AspNetCore.Mvc.Versioning است. سپس باید در فایل Startup.cs در متد ConfigureService کد زیر را نوشت.
|
1 2 3 4 5 6 |
services.AddApiVersioning(options => { options.ReportApiVersions = true; options.DefaultApiVersion = new ApiVersion(1, 0); options.AssumeDefaultVersionWhenUnspecified = true; }); |
سپس به ازای هر ورژن، یک Controller باید نوشت. به کد زیر دقت کنید، این کنترلر مربوط به ورژن 1 است.
|
1 2 3 4 5 6 7 8 9 10 11 |
[ApiVersion("1.0")] [Route("v{v:apiversion}/values")] [ApiController] public class Values1Controller : ControllerBase { [HttpGet] public IEnumerable Get() { return new string[] { "value1 - v1", "value2 - v1" }; } } |
کنترلر زیر مربوط به ورژن دوم است
|
1 2 3 4 5 6 7 8 9 10 11 |
[ApiVersion("2.0")] [Route("v{v:apiversion}/values")] [ApiController] public class Values2Controller : ControllerBase { [HttpGet] public IEnumerable Get() { return new string[] { "value1 - v2", "value2 - v2" }; } } |
با هر تغییر باید در endpoint ها تغییر ایجاد شود. این یکی از اشکالات این روش است. برای حل این مشکل، دو روش دیگر نیز ارائه شده اند.
Versioning از طریق HTTP Header
در این روش باید از طریق هدر های درخواست HTTP، تعیین کنید که می خواهید از کدام ورژن از API استفاده کنید. روش کار بدین صورت است که ابتدا باید در فایل Startup.cs در متد ConfigureService کد زیر را اضافه کرد.
|
1 2 3 4 5 6 7 |
services.AddApiVersioning(options => { options.ReportApiVersions = true; options.DefaultApiVersion = new ApiVersion(1, 0); options.AssumeDefaultVersionWhenUnspecified = true; options.ApiVersionReader = new HeaderApiVersionReader("X-API-Version"); }); |
در این روش هم مانند روش URL به ازای هر ورژن باید یک کنترلر نوشت. کنترلر اول مربوط به ورژن 1
|
1 2 3 4 5 6 7 8 9 10 11 |
[ApiVersion("1.0")] [Route("values")] [ApiController] public class Values1Controller : ControllerBase { [HttpGet] public IEnumerable Get() { return new string[] { "value1 - v1", "value2 - v1" }; } } |
کنترلر دوم مربوط به ورژن دوم
|
1 2 3 4 5 6 7 8 9 10 11 |
[ApiVersion("2.0")] [Route("values")] [ApiController] public class Values2Controller : ControllerBase { [HttpGet] public IEnumerable Get() { return new string[] { "value1 - v2", "value2 - v2" }; } } |
برای تست عملکرد API تنها کافی است در برنامه ی Postman ، در Request Header سربرگی به نام X-API-Version را اضافه کرد. به شکل زیر دقت کنید.
اگر این Header را در Header Request ننویسید، API از ورژن پیشفرض خود استفاده می کند.
Versioning از طریق Query String
در این روش باید ابتدا پارامتر های کوئری را بررسی کرده و مطابق با Version ای که در کوئری آمده است، پردازش را انجام دهید.
https://localhost/api/students?version=1
