سازگارپذیر کردن نسخه‌های API

ایجاد سازگاری در بین نسخه‌های مختلف یک API کاری‌ست که برای مطمئن بودن از قابلیت تعامل با API باید انجام شود. شما در این روال با ارائه نسخه جدیدی از یک API باید مطمئن شوید که مشتریان‌تان که از نسخه قدیمی استفاده می‌کنند هنوز قابلیت تعامل با آن را دارند. در این مطلب از وبسایت راکت قصد داریم در ارتباط با این موضوع نکاتی را ارائه کنیم.

یک مثال ساده

تصور کنید که شما در حال حاضر یک API را توسعه می‌دهید که به صورت آماده توسط مشتریان مختلفی (منظور از مشتریان صرفا شخص نیست، می‌تواند یک ابزار، دستگاه یا اپلیکیشن باشد) استفاده می‌شود. حال اگر شما بخواهید ویژگی‌های جدیدی را به آن API اضافه کنید باید مطمئن شوید که مشتریان هنوز قابلیت کار با API قدیمی را دارند. حال زمانی می‌توانید سازگاری بالایی را ایجاد کنید که بتوانید ویژگی‌های جدید را به صورت نامحسوس از طریق API جدید به مشتریان ارائه کنید. 

برای درک بهتر بگذارید یک مثال عملی را بررسی نماییم: تصور کنید که شما یک متد با نام GetOrders را به عنوان یک API در اختیار دارید. کدهای این قسمت را می‌توانید در زیر مشاهده کنید:

[HttpGet]
[Route("GetOrders")]
 public IActionResult GetOrders(int customerId, int orderId = 0)
 {
   var result = _orderService.GetOrdersForCustomer(
                 customerId, orderId);

   return Ok(result);
 }

در این مثال متد GetOrders یک ID برای مشتری و یک ID برای محصول را دریافت می‌کند که ورودی دوم اختیاری است. حال ما با یک متد دیگر نیز سر و کار داریم که آن را به صورت private تعریف کرده‌ایم:

private List<Order> GetOrdersForCustomer(int customerId, int orderId)
{
   //Write code here to return one or more order records
}

کار متد GetOrdersForCustomer آن است که تمام سفارشات مربوط به یک مشتری را برگرداند. البته از آنجایی که ورودی دوم متد GetOrders اختیاری است و به صورت پیشفرض مقدار 0 دارد.

حال اگر در یک API جدید قصد آن را داشته باشیم که این حالت را تغییر دهیم و ورودی این فیلد را اجباری کنیم، کلاینت‌های قدیمی قادر به کار با این API نخواهند بود. 

[HttpGet]
[Route("GetOrders")]
 public IActionResult GetOrders(int customerId, int orderId)
 {
   var result = _orderService.GetOrdersForCustomer
                 (customerId, orderId);

   return Ok(result);
 }

این دقیقا زمانی‌ست که ما سازگاری را از بین می‌بریم. در ادامه همین مطلب در ارتباط با نکاتی صحبت خواهیم کرد که می‌توانند به شما در ایجاد این سازگاری کمک نمایند.

نکات سازگاری API

حال که ما می‌دانیم مشکل دقیقا کجای کار است، چگونه می‌توانیم آن را حل نماییم؟ چگونه مطمئن شویم که REST APIها سازگاری کامل با نسخه‌های قدیمی خودشان را دارند؟ در زیر می‌توانید لیستی از نکات مربوط به این مورد را مشاهده نمایید.

۱- مطمئن شوید که تست‌های واحد را پیاده‌سازی کرده‌اید

اولین قدم برای این کار تست واحد است. شما باید تست‌هایی بنویسید که بتواند سازگاری APIها را تست کند. در این حالت اگر مشکلی بوجود آمد تست‌ها باید به شما اطلاع دهند که یک ناسازگاری بین نسخه‌های مختلف وجود دارد. می‌توانید از طریق CI/CD این روند را نیز به صورت تست‌های خودکار انجام دهید. این کار میزان احتمال رسیدن به مشکلات را بسیار بیشتر می‌کند.

۲- هیچوقت رفتار کدهای مربوط به HTTP Response را تغییر ندهید

هیچوقت نباید رفتار کدهای HTTP Response را تغییر دهید. برای مثال اگر API در دسترسی به بانک اطلاعاتی مشکل داشت و خطای ۵۰۰ را برمی‌گرداند در نسخه جدید API این مقدار نباید ۲۰۰ باشد. انجام چنین کاری باعث ایجاد ناسازگاری در کدها و در روند اجرای API می‌شود.

۳- پارامترها را تغییر ندهید

از ایجاد نسخه‌‌ای جدید از API زمانی که تنها نیاز به تغییرات کوچکی دارید اجتناب کنید. چرا که انجام این کار ریسک از بین بردن سازگاری را بالا می‌برد. یک رویکرد بهتر برای انجام چنین کاری افزودن پارامترهای جدید به متدهای API است. اما در تعامل با پارامترهای متد API هیچوقت نباید یکی از آن‌ها را حذف کنید و یا تغییر دهید. برای مثال نباید یکی از پارامترها را از حالت اختیاری به حالت اجباری تغییر دهید، کاری که ما در مثال اول این مطلب انجام دادیم. انجام هر یک از این کارها باعث ایجاد ناسازگاری در API می‌شود.

۴- نسخه‌بندی API

نسخه‌بندی API عملکرد مناسبی در تعامل داشتن با قابلیت‌های جدید است. نسخه‌بندی باعث می‌شود تا APIهای شما با تغییرات جدید سازگارتر و تطبیق‌پذیرتر شوند. انجام این کار همچنین در مدیریت بهتر تغییرات به شما کمک می‌کند و به شما این قابلیت را می‌دهد تا بتوانید در صورت وجود مشکل در کدهای جدید سراغ کدهای قدیمی بازگردید. بنابراین شما باید نسخه‌های مختلفی از یک REST API را داشته باشید.

البته با وجود آنکه خود REST راهنما یا قاعده‌ مشخصی در ارتباط با نسخه‌بندی API ارائه نمی‌کند اما می‌توان نسخه‌بندی API را از سه راه متفاوت انجام داد: مشخص کردن اطلاعات مربوط به یک نسخه خاص از طریق URL، ذخیره اطلاعات مربوط به یک نسخه در سربرگ درخواست و یا افزودن اطلاعات مربوط به نسخه API از طریق سربرگ HTTP Accept. اگرچه نسخه‌بندی در نگه‌داری از API می‌تواند به شما کمک بکند اما نباید در ایجاد نسخه‌های مختلف زیاده‌روی کنید. این کار مدیریت‌پذیری APIها را دشوارتر می‌کند.

رویکردهای مناسب دیگر

هیچوقت نباید URL ریشه یک API را تغییر دهید. اگر قصد دریافت اطلاعات جدید از طریق متد API را دارید، پارامترهای جدید باید به صورت اختیاری در نظر گرفته شوند. 

در پایان

ایجاد تغییرات در REST APIها امری اجتناب‌ناپذیر است، اما اگر از این نکات استفاده کنید می‌توانید این کار را در نهایت سازگاری انجام دهید. مطمئن شوید کاری می‌کنید که سازگاری نسخه جدید API با نسخه‌های قدیمی آن را حفظ خواهید کرد. 

منبع