tgoop.com/dotnetcode/3028
Last Update:
یه نگاهی به این عکس باحال بندازیم که پر از نکته‌های کاربردی برای طراحی APIهای خوب و امنه. انگار یه چک‌لیست جمع‌وجور و مفیده که بهمون میگه چی خوبه ✅ و چی نه ❌. از اسم‌گذاری منابع و استفاده از حالت جمع گرفته تا امنیت و فیلتر کردن، کلی چیز میز داره.
اما امروز می‌خوام روی یه قسمت خاصش زوم کنیم که خیلی هم مهمه: نسخه‌بندی یا Versioning API.
چرا اصلاً نسخه‌بندی مهمه؟
فرض کن یه API خفن ساختی و کلی آدم دارن ازش استفاده می‌کنن (مثلاً اپلیکیشن موبایلشون بهش وصله). حالا می‌خوای یه تغییر بزرگ بدی یا یه قابلیت جدید اضافه کنی که ممکنه روش کارکرد قبلی رو خراب کنه. اگه همین‌جوری آپدیتش کنی، یهو می‌بینی اپلیکیشن کاربرات از کار افتاده و کلی آدم شاکی پشت خط داری!
اینجاست که نسخه‌بندی (Versioning) مثل یه فرشته نجات ظاهر میشه! بهت اجازه میده تغییرات جدید رو توی یه "نسخه" جدید از API اعمال کنی، در حالی که نسخه قبلی همچنان برای کاربرای قدیمی کار می‌کنه. اینطوری هم می‌تونی API رو به‌روز نگه داری و هم کاربرای فعلی رو راضی نگه داری. مثل این می‌مونه که همزمان دو تا جاده داشته باشی؛ یکی جاده قدیم برای ماشین‌های قدیمی، یکی هم اتوبان جدید برای اونایی که می‌خوان سریع‌تر برن!
عکس چی میگه؟
توی عکس، ردیف چهارم دقیقاً به همین موضوع اشاره کرده:
* ❌ GET /carts/v1/123 (روش نامناسب)
* ✅ GET /v1/carts/123 (روش مناسب)
این یعنی چی؟ یعنی پیشنهاد می‌کنه که شماره نسخه (مثل v1 برای نسخه اول) رو اول آدرس URL بیاریم. این کار چند تا مزیت داره:
1. واضحه: همون اول کار مشخصه که داریم با کدوم نسخه از API کار می‌کنیم.
2. مسیریابی (Routing) راحت‌تره: برای سرور راحت‌تره که درخواست‌ها رو بر اساس نسخه به کد مربوطه هدایت کنه.
راه‌های دیگه برای نسخه‌بندی هم هست؟
آره! روشی که توی عکس اومده (گذاشتن نسخه توی URL Path) خیلی رایجه، اما تنها راه نیست. چند تا روش متداول دیگه هم داریم:
1. Query Parameter: نسخه رو مثل یه پارامتر عادی توی URL می‌فرستیم:
GET /carts/123?version=1
این روش URL رو شلوغ نمی‌کنه ولی شاید یه کم کمتر به چشم بیاد.
2. Custom Request Header: نسخه رو توی هِدِر (Header) درخواست می‌فرستیم:
Accept: application/vnd.yourapi.v1+json
این روش URL رو کاملاً تمیز نگه می‌داره و از نظر معنایی هم شاید درست‌تر باشه، ولی کار کردن و تست کردنش با مرورگر یه کم سخت‌تره.
کدوم روش بهتره؟
هیچکدوم ذاتاً "بهترین" نیستن. انتخابش بستگی به نیاز پروژه، راحتی تیم و استانداردهایی داره که استفاده می‌کنید. روش URL Path (همونی که تو عکسه) خیلی محبوبه چون ساده و شفافه.
جمع‌بندی
نسخه‌بندی API یه موضوع حیاتی برای مدیریت تغییرات و تکامل APIهاست، بدون اینکه کاربرای فعلی رو اذیت کنیم. این عکس باحال یه روش خوب و رایج (گذاشتن نسخه اول URL) رو پیشنهاد میده. یادت باشه که روش‌های دیگه‌ای هم هست و مهمه که از همون اول طراحی API به فکر نسخه‌بندی باشی.
در کل، این عکس یه منبع عالی پر از نکات کاربردی برای طراحی API هست. حتماً بقیه مواردش رو هم یه نگاه بنداز!
📚💻 @dotnetcode
