قرارداد API پیش از کد: چرا اول باید روی رابط توافق کنیم

در خیلی از پروژه‌ها API آخرین چیزی است که شکل می‌گیرد: سرور چیزی می‌سازد، رابط کاربری چیز دیگری انتظار دارد، و در هفته‌ی آخر معلوم می‌شود این دو با هم جور نیستند. رویکرد «اول قرارداد» این ترتیب را برعکس می‌کند.

قرارداد API یعنی چه

قرارداد API توصیف دقیق این است که دو بخش سامانه چطور با هم حرف می‌زنند: چه درخواست‌هایی وجود دارد، هر کدام چه ورودی می‌گیرد، چه خروجی می‌دهد و در صورت خطا چه اتفاقی می‌افتد.

این قرارداد پیش از نوشتن کد، روی کاغذ یا در قالب‌های استاندارد توصیف API نوشته و تأیید می‌شود.

چرا اول قرارداد

کار موازی

وقتی قرارداد مشخص است، تیم رابط کاربری با داده‌ی نمونه کار می‌کند و تیم سرور همان قرارداد را پیاده می‌کند. هیچ‌کدام منتظر دیگری نمی‌مانند.

پیدا شدن زودهنگام اختلاف

بیشتر سوءتفاهم‌ها در طراحی قرارداد خودشان را نشان می‌دهند: «این فیلد اجباری است؟»، «اگر موجودی صفر بود چه برمی‌گردد؟». پاسخ دادن به این‌ها روی کاغذ چند دقیقه طول می‌کشد؛ در کد چند روز.

یکپارچه‌سازی بدون غافلگیری

مرحله‌ی اتصال بخش‌ها که معمولاً پرتنش‌ترین بخش پروژه است، به یک بررسی ساده تبدیل می‌شود: آیا هر دو طرف به قرارداد پایبند بوده‌اند؟

مستندات رایگان

قراردادی که از ابتدا نوشته شده، خودش مستندات است و کهنه نمی‌شود، چون مبنای کار بوده است.

اصول طراحی یک قرارداد خوب

به زبان محصول، نه پایگاه داده. API نباید آینه‌ی جدول‌ها باشد. کاربر «سفارش ثبت می‌کند»، نه اینکه «در سه جدول ردیف اضافه کند».

ثبات در نام‌گذاری. اگر یک جا createdAt نوشته‌اید، جای دیگر creation_date ننویسید. ناهماهنگی کوچک، خطای بزرگ می‌سازد.

خطاها بخشی از قرارداد‌ند. هر درخواست علاوه بر پاسخ موفق، خطاهای ممکنش را هم باید مشخص کند، با کدهایی که ماشین بتواند بخواند:

{ "ok": false, "code": "RATE_LIMIT", "retryAfter": 60 }

صفحه‌بندی از ابتدا. فهرستی که امروز ده مورد دارد، سال بعد ده‌هزار مورد خواهد داشت.

فقط آنچه لازم است. هر فیلدی که منتشر کنید، تعهد نگهداری آن را پذیرفته‌اید. حذف کردن همیشه سخت‌تر از اضافه کردن است.

اعتبارسنجی در مرز. ورودی باید در همان نقطه‌ی ورود بررسی شود و قاعده‌هایش در قرارداد آمده باشد.

نسخه‌بندی و تغییر

قرارداد ثابت نمی‌ماند، ولی تغییرش باید قاعده داشته باشد:

• اضافه کردن فیلد یا درخواست جدید معمولاً بی‌خطر است.
• حذف یا تغییر معنا همیشه شکننده است و باید با نسخه‌ی جدید و دوره‌ی گذار همراه باشد.
• هر تغییر، اول در قرارداد ثبت می‌شود و بعد در کد.

قرارداد برای مصرف‌کننده‌ی غیرانسانی

امروز مصرف‌کننده‌ی API فقط رابط کاربری نیست. عامل‌های هوش مصنوعی هم ابزارهای خود را از طریق همین قراردادها صدا می‌زنند. برای آن‌ها شفافیت قرارداد حتی مهم‌تر است: توضیح دقیق هر عمل، ورودی‌های مشخص و خطاهای قابل‌فهم، مستقیماً در کیفیت تصمیم عامل اثر دارد.

جایگاه در روش کار

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

این قرارداد همچنین پایه‌ی لایه‌های قابل‌تعویض است: وقتی رابط ثابت باشد، آنچه پشت آن است می‌تواند عوض شود.

اشتباه‌های رایج

• نوشتن قرارداد بعد از کد. در این حالت قرارداد فقط توصیف چیزی است که ساخته شده، نه توافق.
• طراحی در تنهایی. قرارداد را باید مصرف‌کننده و سازنده با هم طراحی کنند.
• نادیده گرفتن خطاها. مسیر موفق فقط نیمی از قرارداد است.
• قرارداد بدون نمونه. یک مثال واقعی از درخواست و پاسخ، از ده پاراگراف توضیح روشن‌تر است.

جمع‌بندی

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

برای طراحی معماری و قراردادهای محصولتان، معماری و برنامه‌ریزی فنی را ببینید.