💡♻️ مفهوم و کاربرد API-First Development

توسعه‌ی نرم‌افزار رو میشه مثل ساختمون، بدون نقشه و طرح معماری ساخت! نگید نمیشه؛ چون خیلیا می‌سازن و شده! 😂 تیم‌ها شروع می‌کنن به دیوارکشی (توسعه فرانت‌اند و بک‌اند)، ولی وقتی می‌رسن به اتصالات (Integration)، می‌بینن لوله‌کشی و سیم‌کشی (API) شبیه خونه‌ی پت‌ومت در اومده که از پریز برق آب میاد، لوله برق داره یا درِ پارکینگ به جای کوچه، به پذیرایی همسایه باز می‌شه؛ ساختمونه هم بین ساختمون‌های مجاورش شبیه جوجه کلاغ وسط صد تا جوجه اردکه!

رویکرد سال‌های دور (دلار هزار تومنی) این بود که API یه "محصول جانبی" برای ارتباط با سایر سیستم‌ها محسوب می‌شد؛ یعنی اول بک‌اند نوشته می‌شد، بعد یه قسمتی از اون رو به‌صورت API در معرض استفاده قرار می‌دادن. ریشه‌های این روش، عموما توی خاک سیستم‌های داده‌محور (Data-First) رشد می‌کرد؛ و کمتر "مصرف‌کننده‌محور" (Consumer-Centric) بود.
از طرفی زیاد دیدیم که تیم‌ها معطل هم برای آماده شدن API می‌مونن! یا اعصابشون سر تغییراتی که تیم مقابل روی APIهاش بعد از تفاهم اولیه داده خورد می‌شه! فرانت می‌گه "API تون درست کار نمی‌کنه"، بکند می‌گه "شما درست صداش نمی‌زنین"، و QA هم وسط این دعوا نرخ تعیین می‌کنه! یه بخش بزرگ از این سردردها از نداشتن یه زبون مشترک و قرارداد واضح بین تیم‌هاست.

از طرف دیگه، خیلی وقت‌ها می‌بینیم که بکند کدش رو نوشته، بعد مستندات رو می‌نویسه، بعد معلوم می‌شه مصرف‌کننده یه چیز دیگه می‌خواسته! حالا برگردیم و دوباره بنویسیم؟ یا همینجوری با کثیف‌کاری وصلش کنیم؟ شنیدن جمله "ما بعداً مستندات رو کامل می‌کنیم!" چیز غریب و نادری نیست! ولی واقعیت اینه که توی تیم‌های بالغ، اول API Spec رو می‌نویسن، بعد کد. اگر هم خیلی بالغ باشن، این Spec رو به عنوان یه قرارداد (Contract) بین تیم‌ها در نظر می‌گیرن و با ابزارهای خودکار، صحت پیاده‌سازی و انطباق عینی با طرح و نقشه‌ی اولیه رو کنترل می‌کنن.

🧭 مفهوم API-First یعنی چی؟
مفهوم API-First یعنی قبل از نوشتن کد، اول API رو طراحی کنیم (عموما توسط معمار این اتفاق می‌افته) یعنی بشینیم، فکر کنیم، بنویسیم که چه endpointهایی داریم، چه input/output هایی، چه status codeهایی، چه headerهایی... و همه‌ی این‌ها رو توی یه فایل OpenAPI Spec یا مشابهش ثبت کنیم.
این یعنی API ما از ابتدا مستند شده، با بیزنس، با پروداکت، با تیم‌های همکار می‌شه سناریوسازی و مرور کرد؛ تغییر داد و منطبقش کرد با نیاز واقعی؛ و بعد به کد! بعتر هم برای تغییرات، اول API Spec تغییر می‌کنه و بعد کد. چه اتفاق میوفته؟

- پیش‌بینی‌پذیری: همه می‌دونن قراره چه داده‌ای رد و بدل بشه.
- موازی‌سازی توسعه: تیم‌های مختلف می‌تونن هم‌زمان پیش برن؛ یکی Mock بسازه، یکی پیاده‌سازی واقعی.
- مستندسازی خودکار: چون API از اول با استانداردهایی مثل OpenAPI تعریف میشه، مستندات همیشه با واقعیت هم‌راستا می‌مونن.
- کیفیت بالاتر: چون قبل از کدنویسی، درباره طراحی و naming و consistency فکر می‌کنی.

اینطوری API Spec شما اولا توی سورس‌کنترل نگهداری می‌شه، همواره نسخه تست، استیج رو به صورت live در دسترسی داریم، API Owner هر دامنه مشخصه؛ هر کی عشقش کشید به هر شکلی یه API نمی‌نویسه، breaking changeها و کانفلیکت‌ها قبل از تغییر در API آشکار می‌شن و کلی مزیت دیگه که از حوصله پست تلگرامی خارجه.

رویکرد API-First فقط یک روش نیست، یک تغییر فرهنگی در سازمان، و تغییر استراتژیک در توسعه نرم‌افزاره. این رویکرد، API رو از یک "افزونه" به یک "محصول اصلی" تبدیل می‌کنه که برای تجربه توسعه‌دهنده، سرعت و کیفیت نهایی خیلی حیاتیه. وقتی API-First باشیم، سیستم‌های ما در برابر تغییرات مقاوم‌تر، انعطاف‌پذیرتر و آماده‌تر برای Integration Economy خواهند بود. یکی از شرکت‌هایی که بر اساس رویکرد API First کار می‌کنه زالاندو است که اتفاقا خیلی سخاوتمندانه، یا به توصیف دقیق‌تر، هوشمندانه، دستورالعمل و راهنمای خودش رو سال‌هاست به صورت کدباز منتشر کرده و به نظر من بسیار مستند پخته و خوبیه.

پیشنهاد می‌کنم API رو با ساده‌سازی‌هایی که go, fastAPI, flask, .NET یه موضوع خیلی ساده نبینیم، طراحی و نگهداری بد، مصیبت‌های خودش رو در بلندمدت نشون می‌ده، موقع اینتگریشن‌های بعدی نشون می‌ده و اون وقته که متوجه می‌شیم ای کاش از ابتدا مشورت گرفته بودیم و صرف «کار کردن» API به خودمون نمره قبولی نمی‌دادیم! حتمن این روش پرهزینه‌تر و نیازمند زمان‌ آماده‌سازی و توسعه بیشتریه، ولی عملا سرمایه‌گذاری زمان رشد و اینتگریشن خواهد بود.

Zalando RESTful API and Event Guidelines