APIها و مستندات آنها معمولاً از یکدیگر خارج-از-هماهنگی می‌شوند. و این اتفاق بیشتر از آنچه فکر کنید رخ می‌دهد. درواقع، ۷۵٪ از APIها مطابق با مشخصات خود نیستند، براساس یک گزارش اخیر درباره دریفت API. دریفت API می‌تواند باعث منابع ناهماهنگ برای توسعه‌دهندگان، مشکلات تجربه توسعه‌دهنده و حتی یکپارچه‌سازی‌های خراب و مشتریان ناراضی شود. بدتر اینکه دریفت API تشخیص‌دادنش دشوار است، و آن را به یک «قاتل خاموش» تبدیل می‌کند.
این امر به این دلیل است که دریفت API تا حدی از کمبود دید (visibility) ناشی می‌شود. «براساس تحقیقات ما، میان معماری API و توسعه API در بسیاری از تیم‌ها یک ناهماهنگی دائمی وجود دارد»، جیمی بکلند، مدیر ارشد محصول APIContext می‌گوید. «به‌ویژه، معماران دیدی نسبت به شکاف‌ها میان APIهای در محیط تولید و مشخصات مربوطه ندارند.» هنگامی که رهبران فناوری نمی‌توانند ببینند APIهای تولید چگونه از مشخصات منحرف می‌شوند، دشوار است تشخیص دهند چه چیزی نیاز به تغییر دارد.
اما ریشه‌های مشکل عمیق‌تر می‌روند. در ادامه، عوامل اصلی ایجاد دریفت API را بررسی می‌کنیم و نگاهی می‌اندازیم به اینکه چگونه رهبری مهندسی می‌تواند فرهنگ داخلی خود را برای توسعه API هدفمندتر کند. امیدواریم با دنبال‌کردن این نکات، سازمان‌ها بتوانند منابع به‌روزتری نگه دارند و احتمال دریفت API را کاهش دهند.
علل کلیدی دریفت API
چند علت ریشه‌ای احتمالاً پشت دریفت API قرار دارند. یکی از نکات برجسته این است که مستندات API معمولاً ناقص هستند. تنها ۱۰٪ از سازمان‌ها APIهای خود را به‌طور کامل مستندسازی می‌کنند، طبق یک گزارش EMA در سال ۲۰۲۳. بدون یک فرهنگ قوی مستندسازی یا مدیریت موجودی API جامع، معمول است که استفاده‌ای ناهماهنگ از توصیف سرویس‌ها مشاهده شود.
علاوه بر این، بسیاری از گروه‌ها هنوز در مراحل ابتدایی استراتژی‌های حاکمیت API خود هستند. با افزایش تعداد APIها در یک شرکت، آنهایی که استانداردهای تثبیت‌شده برای نگه‌داری چرخه‌عمر API ندارند، بیشتر دچار ناسازگاری یا تبدیل سرویس‌ها به APIهای سایه یا زامبی می‌شوند.
براساس گفته لورنا میچل، معاون تجربه توسعه‌دهنده در Redocly، دریفت API ذاتاً به نبود تست جامع مرتبط است.
برای APIهای طراحی-اول، اگر تست‌های واضحی وجود نداشته باشد که بررسی کند آنچه ساخته شده با آنچه توصیف شده مطابقت دارد یا نه، دریفت می‌تواند رخ دهد. این مشکلی است که می‌تواند به‌راحتی فراگیر شود، او می‌گوید: «کد تکرار می‌شود و شکاف عمیق‌تر می‌شود.»
هر سازمانی هم انتظارات طراحی-اول یا الزام انطباق با مشخصات را اعمال نمی‌کند. بنابراین، نبود توسعه مشخصات-اول نیز علت محتمل دیگری برای دریفت است. «احتمالاً بسیاری از APIها وجود دارند که حتی اگر بخواهند هم نمی‌توانند از OpenAPI استفاده کنند»، کوین سویبر، رهبر استراتژی API در Postman می‌گوید. «این هرگز به ۱۰۰٪ پذیرش نزدیک نخواهد شد، و این هم نباید هدف باشد.»
راجش کامیستی، معمار راهکارهای دیجیتال، اضافه می‌کند دریفت از کمبود دسترسی به ابزارها و مهارت‌های لازم برای تولید مشخصات OpenAPI باکیفیت همراه با شِماها و مثال‌ها ناشی می‌شود. حاکمیت ناموجود یا ناکارآمد، همراه با بلوغ مهندسی پایین و فرهنگ مستندسازی نوپا، این موضوع را تشدید می‌کند. از این لحاظ، دریفت مشخصات API شاید فقط نشانه‌ای از یک مشکل بزرگ‌تر باشد.
در مجموع، دریفت API یک نتیجه ناخواسته است که به کمبود انضباط بازمی‌گردد، امانوئل پاراسکاکیس، مدیرعامل Level 250 می‌گوید. «انضباط برای طراحی و ارائه محصولات API به‌صورت عمدی، همراه با بازخورد بازار و مصنوعات طراحی که باید دنبال شوند. هنگامی که حتی نمی‌توانید توافق کنید از چه چیزی منحرف شده‌اید، دریفت تضمین‌شده است.»
اثرات منفی دریفت
بدون سیاست‌های روشن مدیریت تغییر، APIها به‌راحتی از شکل و عملکرد مستند شده خود منحرف می‌شوند. وقتی این اتفاق بیفتد، هر چیزی که به «منبع حقیقت» متصل باشد نیز نادرست می‌شود. «توصیف OpenAPI با واقعیت مطابقت ندارد و بنابراین مستندات، SDKها یا هر چیز دیگر نیز مطابقت ندارند»، میچل از Redocly می‌گوید.
این نوع دریفت می‌تواند تجربه توسعه‌دهنده و بهره‌وری او را منفی تحت تأثیر قرار دهد. «وقتی مشخصات منحرف می‌شوند، دیگر منبع حقیقت نیستند»، کامیستی می‌گوید. «این می‌تواند منجر به اشتباه رفتن مصرف‌کنندگان، فرضیات نادرست، کاهش بهره‌وری یا مشکلات بدتر اجرایی شود.»
دیگران موافق‌اند که توسعه‌دهندگان نهایی معمولاً بیشترین ضربه را از دریفت API می‌خورند. «براساس تحقیقات ما، تجربه کاربر نهایی به‌شدت تحت تأثیر دریفت API قرار می‌گیرد»، بکلند از APIContext می‌گوید. «بیشتر تیم‌ها امیدوارند API آنها خود-سرویس باشد، اما وقتی مستندات با عملکرد واقعی همسو نیست، کاربران نهایی نمی‌توانند به‌تنهایی مشکل را حل کنند.»
وقتی دریفت API تجربه توسعه‌دهنده را مختل کند، می‌تواند اثرات منفی پایین‌دستی برای کسب‌وکار ایجاد کند. یعنی تبدیل کمتر، ریزش بالا، امتیاز NPS پایین و اتلاف منابع، پاراسکاکیس از Level 250 می‌گوید. نبود یک مشخصات نگه‌داری‌شده خوب همچنین می‌تواند هزینه‌های پشتیبانی را افزایش دهد.
راه‌های جلوگیری از دریفت API
چگونه تیم‌های API می‌توانند از دریفت جلوگیری کنند؟
چه ابزارها، فرآیندها، گردش‌کارها یا ذهنیت‌های فرهنگی می‌توانند کمک کنند تا توصیفاتی که مطابق APIها هستند حفظ شوند؟ بیایید برخی روش‌هایی را بررسی کنیم که تیم‌های API می‌توانند برای کاهش فعال دریفت و حفظ تعاریف دقیق API که در هم‌زمانی باقی می‌مانند، استفاده کنند.
استفاده از OpenAPI به‌عنوان منبع حقیقت
به حداقل رساندن دریفت نیازمند ایجاد فرهنگی بر پایه انضباط و هدف‌مندی و متمرکز کردن تغییرات روی مصنوعات مانند اسناد OpenAPI است، پاراسکاکیس می‌گوید. «مصنوعات را به‌اشتراک بگذارید و بررسی کنید. توافق کنید چه چیزی باعث می‌شود این مصنوعات قابل انتشار و مناسب برای ساخت محصول باشند.» او می‌گوید. «سپس از اتوماسیون و ابزارها استفاده کنید تا همترازی با نیت حفظ شود.»
جدا کردن مستندات API از کد
کامیستی نگاه کمی متفاوت دارد و تأکید می‌کند که مشخصات API شایسته مخزن اختصاصی خود هستند و باید به‌عنوان محصولاتی مستقل درنظر گرفته شوند. «مشخصات API و مستندات باید جدا از کد پیاده‌سازی در نظر گرفته شوند»، او می‌گوید. «با انتقال آنها به مخزن مخصوص خود، APIها می‌توانند مانند محصولات رفتار شوند، با مستنداتی اختصاصی که توسط نویسندگان فنی یا تحلیل‌گران نگه‌داری می‌شود تا نیازهای کسب‌وکار و مصرف‌کننده را برآورده کنند.»
اتوماسیون تولید مستندات
ابزارهایی مانند swagger-core برای توسعه‌دهندگان Java کمک می‌کنند مشخصات OpenAPI را از annotationهای کد تولید کنند. با این حال، کامیستی هشدار می‌دهد که این رویکرد هنوز می‌تواند به دریفت منجر شود اگر annotationها به‌طور پیوسته به‌روزرسانی نشوند و زمینه مهم برای مصرف‌کننده از دست برود. استفاده از ابزارهایی که مستندات را از مشخصات و نه از کد تولید می‌کنند می‌تواند به همترازی APIها با مشخصات کمک کند.
یکپارچه‌سازی تست مشخصات در CI/CD
اجرای تست‌هایی برای بررسی همترازی API و مشخصات در هر استقرار یک روش مؤثر دیگر است. این می‌تواند شامل بررسی‌های تطابق در خط لوله CI/CD در هر انتشار باشد. ابزارهایی مانند oasdiff می‌توانند به شناسایی تفاوت‌ها میان نسخه‌های OpenAPI کمک کنند و باعث شوند توسعه‌دهندگان تغییرات احتمالی شکننده را پیش از رسیدن به تولید تشخیص دهند. ابزارهایی مانند Spectral یا Optic نیز می‌توانند APIها را lint کنند تا مطمئن شوند مشخصات از قوانین خاصی پیروی می‌کنند.
استفاده از تست قرارداد (Contract Testing)
تست قرارداد روشی دیگر برای اعمال پایبندی به مشخصات از طریق بررسی تعاملات است. تست قرارداد محیط تولید را آزمایش می‌کند تا مطمئن شود با رفتارهای موردانتظار یا قرارداد مطابقت دارد. همان‌طور که قبلاً پوشش داده‌ایم، ابزارهای زیادی برای تست قرارداد وجود دارد، مانند Pactflow، Karate، Hypertest و دیگران. «افزودن تست قرارداد به‌عنوان بخشی از خط لوله توصیف API پس از linting و قبل از هر مرحله تبدیل برای انتشار رویکرد خوبی است»، میچل می‌گوید.
داشتن فرآیند تکرارشونده برای به‌روزرسانی OpenAPI
«این مشکل دریفت بزرگ‌ترین مانع موفقیت با OpenAPI است»، میچل می‌گوید. «مردم سعی می‌کنند کد API را به توصیف آن قفل کنند و در نهایت توصیف OpenAPI را تولید می‌کنند.» با این حال، این می‌تواند منجر به مشکلاتی شود چون معمولاً اطلاعات حداقلی در کد وجود دارد و آگاهی کافی فرآیندی درباره نحوه اصلاح تکرارشونده توصیف‌های OpenAPI پس از تولید وجود ندارد. در این زمینه، مشخصات جدید Overlay قرار است کمک کند.
انعطاف‌پذیر بودن
در حالی که حفظ سازگاری حیاتی است، انعطاف‌پذیری گاهی هنگام تفاوت میان واقعیات تولید و طراحی‌های اولیه ضروری است. «علاوه بر ابزارها، مهم است که هر دو طرف انعطاف‌پذیر باشند، زیرا معمولاً دلایل عملی وجود دارد که چرا پیاده‌سازی‌های API با طراحی اولیه متفاوت است»، بکلند از APIContext می‌گوید. «بسته به میزان اختلاف، گاهی منطقی است API را تغییر دهید، و گاهی پاسخ درست تغییر مشخصات است.»
آیا کاهش دریفت ارزشش را دارد؟
هر رویه فنی جدید دارای هزینه‌هایی است. بنابراین، حتی اگر امکان کاهش دریفت وجود داشته باشد، آیا ارزش تلاش دارد؟ طبق گفته میچل، اجتناب از دریفت مزایای زیادی دارد زیرا به معنی هم‌زمان بودن همه است. این موضوع ادغام را آسان‌تر می‌کند و انطباق امنیتی و الزامات ممیزی را ساده‌تر می‌سازد. این مزایا ارزش زحمت لازم برای تشخیص و رفع دریفت را دارند.
این گفته، منابع موردنیاز برای سرمایه‌گذاری در کاهش دریفت بسته به اندازه شرکت متفاوت است. در مقیاس کوچک، رفع دریفت به‌صورت دستی آسان است، اما در استقرارهای بزرگ نیاز به فرآیند دارد، پاراسکاکیس می‌گوید: «در مقیاس بزرگ، این غیرقابل مدیریت است و سرمایه‌گذاری روی استحکام کاملاً ارزشمند است.»
به‌صورت عملی، همه رخدادهای دریفت نیازمند پاسخ‌های بزرگ نیستند. «همه اختلاف‌ها اهمیت یکسان ندارند»، بکلند می‌گوید و بر نیاز به ابزارهای تطابق تأکید می‌کند که اختلافات را دنبال کنند تا تیم‌ها بتوانند اولویت‌بندی کنند. «مدیران محصول اغلب می‌توانند در تصمیم‌گیری میان این ملاحظات کمک کنند وقتی سطح مشکل را درک کنند.»
«ارزش این را دارد که امتحان کنید و ببینید آیا کار می‌کند یا نه»، کامیستی می‌گوید. او پیشنهاد می‌کند یک شاخص دریفت بسازید تا میزان دریفت را کمی‌سازی کنید و توافق‌نامه‌های سطح خدمات (SLA) برای رسیدگی به دریفت ایجاد کنید. یادگیری ماشینی، از طریق محصولاتی مانند Traceable، می‌تواند کمک کند یک شِما و endpointهای نرمال‌شده ساخته شود که با مشخصات API مقایسه شوند. استفاده از نسخه‌بندی و اعتبارسنجی خودکار مشخصات در برابر endpointها و payloadها نیز می‌تواند به کاهش دریفت کمک کند.
جمع‌بندی نهایی
دریفت API یک مشکل چندوجهی است با ریشه‌های بالقوه گوناگون و تعداد زیادی راهکار مقابله. از آنجا که ماشین‌ها عمدتاً APIها را مصرف می‌کنند، دریفت اغلب بی‌توجه باقی می‌ماند و نیازمند تلاش‌های متمرکز برای تشخیص و فرآیندهای نگه‌داری منعطف و قابل اعتماد است.
یکی از راه‌ها برای برجسته‌کردن مشکل دریفت API مقایسه آن با مشکلات UI است. «من دریافته‌ام که آنچه در مکالمات مشتریان اثرگذار است مقایسه طراحی محصول API، تحویل و نگه‌داری آن با محصولات مبتنی بر UI است»، پاراسکاکیس می‌گوید. «هیچ‌کس مخالف داشتن یک طراحی در Figma نیست، یا بررسی طراحی و ثبت اشکالات اگر UI از نیت منحرف شود.»
علاوه بر افزایش آگاهی، حل دریفت به تعیین مالکیت نیز وابسته است. همان‌طور که بکلند بیان می‌کند: «مانند بسیاری از مشکلات API، مالکان بالقوه متعددی وجود دارند، که اغلب به این معنی است که هیچ مالک مشخصی در سازمان وجود ندارد.» پیشاپیش چیزهای زیادی برای مدیریت API وجود دارد از طراحی، سبک و امنیت گرفته تا آمادگی تولید، بازاریابی و تجربه توسعه‌دهنده.
افزودن مدیریت دریفت بر این انبوه کار بیشتر می‌طلبد، اما از منظر کاربر و کسب‌وکار ارزشمند است. برای رسیدن به آن، ابزارهایی لازم است که دریفت را شناسایی کنند و گردش‌کارهای تکرارشونده‌ای که همه چیز را در همترازی نگه دارند. فرهنگی نیز به اشتراک دانش بیشتر و شفاف‌سازی مسئولیت‌ها نیاز دارد.
