API یکی از مهم‌ترین اجزای ارتباط میان نرم‌افزارها، سرویس‌ها و اپلیکیشن‌هاست. بسیاری از وب‌سایت‌ها و اپلیکیشن‌ها برای دریافت اطلاعات، ارسال درخواست یا ارتباط با سرویس‌های دیگر به API وابسته‌اند. اما با گذشت زمان، APIها نیز مانند هر بخش دیگری از یک سیستم نرم‌افزاری قدیمی می‌شوند و ممکن است دیگر پاسخگوی نیازهای جدید نباشند.
مشکل زمانی ایجاد می‌شود که یک API قدیمی همچنان توسط چندین سرویس یا نرم‌افزار مورد استفاده باشد. در این شرایط، تغییر مستقیم API می‌تواند باعث از کار افتادن بخشی از سیستم یا ایجاد خطا برای کاربران شود. به همین دلیل، به‌روزرسانی APIهای قدیمی بدون اختلال در سرویس‌ها نیازمند برنامه‌ریزی، آزمایش و یک فرایند مهاجرت مرحله‌ای است.
در این مقاله بررسی می‌کنیم چگونه می‌توان APIهای قدیمی را به‌روزرسانی کرد، بدون اینکه سرویس‌های وابسته به آن دچار مشکل جدی شوند.
چرا به‌روزرسانی APIهای قدیمی چالش‌برانگیز است؟
API در واقع یک قرارداد میان سرویس ارائه‌دهنده و مصرف‌کنندگان آن است. کلاینت‌ها بر اساس همین قرارداد می‌دانند چه درخواستی ارسال کنند، چه داده‌ای دریافت کنند و چگونه پاسخ API را پردازش کنند. بنابراین حتی یک تغییر ظاهراً ساده می‌تواند روی سرویس‌های دیگر تأثیر بگذارد.
برای مثال، فرض کنید یک API در پاسخ خود فیلدی با نام customer_name برمی‌گرداند و چندین اپلیکیشن از همین نام استفاده می‌کنند. اگر این فیلد حذف یا به name تغییر داده شود، کد کلاینت‌هایی که هنوز منتظر customer_name هستند ممکن است با خطا مواجه شود.
تغییراتی مانند حذف یا تغییر نام پارامترها، تغییر نوع داده، اجباری کردن یک پارامتر اختیاری یا تغییر رفتار یک عملیات از نمونه‌های رایج Breaking Change هستند. (Microsoft Learn)
بنابراین قبل از هر تغییری باید مشخص شود کدام بخش‌های API قابل تغییر هستند و کدام تغییرات می‌توانند سازگاری با نسخه‌های قبلی را از بین ببرند.
ابتدا وابستگی‌های API را شناسایی کنید
یکی از مهم‌ترین اشتباهات هنگام به‌روزرسانی API این است که تیم توسعه فقط خود API را بررسی کند و مصرف‌کنندگان آن را نادیده بگیرد.
قبل از شروع کار باید مشخص شود چه سرویس‌ها، اپلیکیشن‌ها، میکروسرویس‌ها یا مشتریانی از API موردنظر استفاده می‌کنند. برای هر مصرف‌کننده بهتر است اطلاعاتی مانند نسخه مورد استفاده، میزان استفاده، endpointهای فراخوانی‌شده و وضعیت مهاجرت ثبت شود.
اگر API عمومی باشد، این مرحله اهمیت بیشتری دارد؛ زیرا ممکن است تیم توسعه‌دهنده کنترل مستقیمی روی همه مصرف‌کنندگان نداشته باشد.
استفاده از لاگ‌ها، ابزارهای مانیتورینگ، مستندات API و داده‌های مربوط به درخواست‌ها می‌تواند برای شناسایی این وابستگی‌ها مفید باشد.
تفاوت تغییرات سازگار و ناسازگار را مشخص کنید
همه تغییرات API الزاماً خطرناک نیستند. برخی تغییرات را می‌توان بدون ایجاد نسخه جدید انجام داد، در حالی که برخی دیگر نیاز به نسخه‌بندی دارند.
برای نمونه، اضافه کردن یک endpoint جدید معمولاً یک تغییر افزایشی است. اضافه کردن یک فیلد جدید به پاسخ نیز در بسیاری از طراحی‌ها تغییر سازگار محسوب می‌شود؛ به شرطی که کلاینت‌ها بتوانند فیلدهای ناشناخته را نادیده بگیرند. در مقابل، حذف یک فیلد موجود یا تغییر نوع آن می‌تواند یک تغییر ناسازگار باشد. (GitHub Docs)
به همین دلیل، پیش از انتشار نسخه جدید باید فهرستی از تغییرات تهیه شود و برای هر مورد مشخص شود که آیا Backward Compatible است یا خیر.
نسخه‌بندی API را جدی بگیرید
اگر تغییر موردنظر با نسخه قبلی سازگار نیست، یکی از راهکارهای اصلی استفاده از API Versioning است.
برای مثال، به جای اینکه API فعلی را مستقیماً تغییر دهید، می‌توانید نسخه جدیدی مانند v2 ایجاد کنید و نسخه v1 را برای مدتی در دسترس نگه دارید.
در این حالت:
- مصرف‌کنندگان قدیمی همچنان از v1 استفاده می‌کنند.
- سرویس‌های جدید به‌تدریج به v2 منتقل می‌شوند.
- تیم توسعه فرصت کافی برای آزمایش نسخه جدید دارد.
- مهاجرت کاربران می‌تواند مرحله‌ای انجام شود.
Microsoft نیز برای تغییرات ناسازگار، ایجاد نسخه جدید و ارائه مسیر مشخص برای مهاجرت مصرف‌کنندگان قبلی را توصیه می‌کند. (GitHub)
روش نسخه‌بندی می‌تواند متفاوت باشد؛ برای مثال نسخه ممکن است در URL قرار گیرد یا به‌صورت پارامتر یا Header مشخص شود. مهم‌تر از شکل انتخابی، این است که سیاست نسخه‌بندی برای کل سیستم روشن و قابل پیش‌بینی باشد.
API جدید را قبل از حذف API قدیمی آزمایش کنید
یکی از روش‌های کم‌ریسک، اجرای هم‌زمان نسخه قدیمی و جدید است. در این روش ابتدا نسخه جدید در محیط آزمایشی بررسی می‌شود و پس از اطمینان از عملکرد آن، بخشی از درخواست‌ها به نسخه جدید هدایت می‌شوند.
برای مثال می‌توان ابتدا API جدید را فقط برای تیم داخلی فعال کرد. پس از رفع خطاهای احتمالی، درصد محدودی از ترافیک به نسخه جدید منتقل شود و در صورت عملکرد مناسب، این انتقال افزایش پیدا کند.
این روش کمک می‌کند مشکلات احتمالی قبل از آنکه تمام کاربران را تحت تأثیر قرار دهند شناسایی شوند.
تست API را قبل از مهاجرت کامل انجام دهید
صرفاً اینکه API جدید در محیط توسعه بدون خطا کار می‌کند، به معنای آماده بودن آن برای محیط واقعی نیست.
تست‌ها باید سناریوهای واقعی مصرف API را پوشش دهند. علاوه بر تست عملکرد endpointها، باید بررسی شود که آیا پاسخ‌های جدید با کد مصرف‌کنندگان قبلی سازگار هستند یا خیر.
تست‌های خودکار نیز اهمیت زیادی دارند. اگر مجموعه‌ای از تست‌های قرارداد یا Contract Testing در اختیار داشته باشید، می‌توانید تغییرات API را قبل از انتشار از نظر سازگاری با سرویس‌های وابسته بررسی کنید.
Google Cloud نیز برای تغییر نسخه API، آزمایش کد کلاینت پس از مهاجرت را بخشی از فرایند ارتقا می‌داند. (Google Cloud Documentation)
از Deprecation به جای حذف ناگهانی استفاده کنید
اگر قرار است API قدیمی در نهایت حذف شود، بهتر است آن را بدون اطلاع قبلی غیرفعال نکنید.
در فرایند Deprecation ابتدا اعلام می‌شود که یک نسخه یا endpoint قدیمی دیگر مسیر توسعه آینده نیست و کاربران باید به نسخه جدید مهاجرت کنند. سپس یک بازه زمانی مشخص برای مهاجرت در نظر گرفته می‌شود.
مستندات API نیز باید وضعیت نسخه‌های مختلف و زمان پایان پشتیبانی را مشخص کنند. برای نمونه، GitHub در API خود تغییرات ناسازگار را در نسخه جدید ارائه می‌کند و پیش از پایان پشتیبانی نسخه قدیمی، اطلاعات مربوط به زمان منسوخ‌شدن آن را در اختیار مصرف‌کنندگان قرار می‌دهد. (GitHub Docs)
این رویکرد باعث می‌شود تیم‌های مصرف‌کننده بتوانند برنامه مهاجرت خود را تنظیم کنند و با حذف ناگهانی سرویس مواجه نشوند.
مانیتورینگ را در زمان مهاجرت افزایش دهید
حتی پس از انتشار نسخه جدید، کار تمام نشده است. باید مشخص شود چه تعداد درخواست هنوز به نسخه قدیمی ارسال می‌شود و آیا نسخه جدید با خطا یا افت عملکرد مواجه شده است یا خیر.
شاخص‌هایی مانند نرخ خطا، زمان پاسخ، تعداد درخواست‌ها، خطاهای HTTP و مصرف منابع می‌توانند اطلاعات ارزشمندی در اختیار تیم فنی قرار دهند.
همچنین بهتر است مشخص شود کدام مصرف‌کنندگان هنوز از نسخه قدیمی استفاده می‌کنند. اگر مثلاً بعد از چند هفته همچنان بخش قابل توجهی از ترافیک روی v1 قرار داشته باشد، شاید لازم باشد مستندات، اطلاع‌رسانی یا فرایند مهاجرت دوباره بررسی شود.
چه زمانی می‌توان API قدیمی را حذف کرد؟
حذف API قدیمی باید آخرین مرحله مهاجرت باشد، نه اولین قدم.
پیش از حذف باید مطمئن شوید که مصرف‌کنندگان اصلی به نسخه جدید منتقل شده‌اند، میزان استفاده از نسخه قدیمی به سطح قابل قبول رسیده و نسخه جدید نیز از نظر عملکرد و پایداری وضعیت مناسبی دارد.
همچنین بهتر است زمان دقیق پایان پشتیبانی از قبل اعلام شود. Microsoft در راهنمای API خود تأکید می‌کند که نسخه‌های قبلی باید وضعیت پشتیبانی مشخص و مسیر مهاجرت روشنی داشته باشند. (GitHub)
مدت زمان نگهداری نسخه قدیمی عدد ثابتی برای همه پروژه‌ها ندارد و به نوع API، تعداد مصرف‌کنندگان، حساسیت سرویس و توافق‌های سازمانی بستگی دارد.
یک مسیر پیشنهادی برای مهاجرت بدون اختلال
به‌طور خلاصه، می‌توان فرایند به‌روزرسانی API قدیمی را در چند مرحله دنبال کرد:
بررسی → شناسایی وابستگی‌ها → دسته‌بندی تغییرات → طراحی نسخه جدید → تست → انتشار تدریجی → مانیتورینگ → اعلام Deprecation → مهاجرت مصرف‌کنندگان → حذف نسخه قدیمی
مهم‌ترین نکته این است که این مراحل را به شکل ناگهانی و هم‌زمان اجرا نکنید. هرچه تعداد مصرف‌کنندگان API بیشتر باشد، مهاجرت تدریجی اهمیت بیشتری پیدا می‌کند.
در معماری‌هایی که چند نسخه API به‌صورت هم‌زمان اجرا می‌شوند، هزینه نگهداری، تست و عملیات نیز افزایش پیدا می‌کند؛ بنابراین نسخه قدیمی نباید برای همیشه باقی بماند و باید از ابتدا برای پایان چرخه عمر آن برنامه داشت. (Microsoft Learn)
در آخر…
به‌روزرسانی APIهای قدیمی بدون اختلال بیشتر از اینکه به تغییر کد وابسته باشد، به مدیریت صحیح فرایند مهاجرت وابسته است. ابتدا باید مصرف‌کنندگان و وابستگی‌های API شناسایی شوند، سپس تغییرات ناسازگار از تغییرات سازگار جدا شوند. در صورت وجود Breaking Change، ایجاد نسخه جدید، آزمایش دقیق، اجرای هم‌زمان نسخه‌ها، انتشار تدریجی و اعلام Deprecation می‌تواند ریسک اختلال را کاهش دهد.
در نهایت، زمانی باید نسخه قدیمی حذف شود که مصرف‌کنندگان آن به نسخه جدید منتقل شده باشند و داده‌های مانیتورینگ نیز نشان دهند وابستگی مهمی به نسخه قدیمی باقی نمانده است.
اگر درباره مسائل فنی، توسعه نرم‌افزار یا تصمیم‌گیری در زمینه فناوری اطلاعات نیاز به راهنمایی دارید، می‌توانید برای اطلاعات بیشتر با مشاوران حرفه‌ای ما در پلتفرم مشاوره جامع و آنلاین الو کمک در ارتباط باشید.
حالا نوبت شماست؛ اگر تجربه کار با یک API قدیمی یا مهاجرت از یک نسخه به نسخه جدید را داشته‌اید، بزرگ‌ترین چالشی که هنگام این فرایند با آن مواجه شدید چه بوده است؟ تجربه‌تان را در بخش دیدگاه‌ها با ما به اشتراک بگذارید.
برای آشنایی بیشتر با موضوعات مرتبط، مقالات زیر را مطالعه کنید:
AIOps چیست و چگونه به مدیریت هوشمند زیرساخت IT کمک می‌کند؟
چگونه APIهای قدیمی را بدون اختلال در سرویس‌ها به‌روزرسانی کنیم؟
FinOps چیست؟ راهنمای مدیریت و کاهش هزینه‌های سرویس‌های ابری
چگونه هزینه زیرساخت IT شرکت را بدون کاهش کیفیت کنترل کنیم؟
Zero Trust چیست و چه زمانی یک کسب‌وکار به معماری اعتماد صفر نیاز دارد؟
چگونه یک سیستم مدیریت رمز عبور امن برای کسب‌وکار انتخاب کنیم؟
