رویکرد API شعار ریزخدمات نیست. ترتیب انتشار است: قرارداد رابط پیش از شروع پیاده‌سازی بازبینی می‌شود. رساله روی فیلدینگ شش قید منبع‌محور تعریف کرد. OpenAPI ۳.x همان جایی است که بیشتر تیم‌ها آن قیود را می‌نویسند. این صفحه پرونده تصمیم است: کی نسخه بزنید، تغییر شکننده چیست، و تیم پنج‌نفره چگونه بدون فرقه سکو برمی‌گردد.
اول قرارداد را منتشر کنید
سند OpenAPI را بنویسید، شکل خطا را با مصرف‌کننده بازبینی کنید، و مسیر سالم را پیش از اسپرینت هندلر منجمد کنید. شش قید فیلدینگ آزمون است: آیا رابط منبع‌محور است، یا رویه از راه دوری است که لباس URL پوشیده؟
قرارداد قابل بازبینی شامل شِمای درخواست و پاسخ، احراز هویت، کدهای وضعیت، انتظار تکرارپذیری و نمونه‌های مشخص است. فهرست مسیر بدون رفتار خطا هنوز مصرف‌کننده را مجبور می‌کند قرارداد واقعی را از کد در حال اجرا کشف کند.
چه چیزی تغییر شکننده است
حذف یا تغییرنام فیلد، تنگ‌کردن نوع، تغییر احراز یا تغییر پیش‌فرض صفحه‌بندی شکننده است. افزودن فیلد اختیاری معمولاً نیست. اگر نتوانید بگویید تفاوت در کدام سطل است، آماده استقرار نیستید.
حتی فیلد افزوده میتواند کلاینت سخت‌گیری را که ویژگی ناشناخته را رد می‌کند بشکند، پس سازگاری باید با مصرف‌کننده واقعی آزموده شود. تغییر صرفاً مستندات، نقطه اختیاری تازه یا ورودی پذیرفته‌شده گسترده‌تر معمولاً وقتی رفتار قابل مشاهده سازگار بماند شکننده نیست.
- حذف فیلد۴ امتیاز
- تغییرنام فیلد۳ امتیاز
- تنگ‌کردن نوع۲ امتیاز
- تغییر احراز۵ امتیاز
امتیاز شدتِ نمونه‌ای برای انواع شکستی که API استارتاپ باید نسخه بزند — فراوانی اندازه‌گیری‌شده نیست. (2026-08).
نسخه‌بندی کارشده برای تیم پنج‌نفره
تا یک شکست /v1 را نگه دارید. /v2 را برای یک دوره صورتحساب موازی کنید. تاریخ انقضا بزنید. پوشه را به‌جای نسخه تغییرنام ندهید. تیم مشهدی که ارائه‌دهنده پرداخت محلی را یکپارچه می‌کند باید منبع پرداخت را جدا از منبع کاربر نسخه بزند تا تغییر API بانک ورود را بازنویسی نکند.
در نمونه دوم، جایگزینی وضعیت رشته‌ای با فهرست بسته مقادیر میتواند مقادیری را رد کند که بیلد موبایل موجود هنوز می‌فرستد. v1 را برای شکل قدیمی باز نگه دارید، فهرست نسخه v2 را با نمونه مهاجرت منتشر کنید و v1 را فقط وقتی بردارید که تله‌متری خروج کلاینت قدیمی از پنجره پشتیبانی را نشان دهد.
برگشت بخشی از قرارداد است
اگر نتوانید قرارداد قبلی را — هندلرها و آخرین شِمای منتشرشده — برگردانید رویکرد API ندارید. امید دارید. آخرین فایل OpenAPI منتشرشده را کنار ران‌بوک نگه دارید. برگشتی که شِما را جا می‌اندازد برگشت نیست.
تغییر پایگاه داده باید همان مرز را رعایت کند: ابتدا ذخیره‌سازی افزایشی، بعد خواننده‌ها، سپس نویسنده‌ها و حذف فیلد قدیمی در پایان. اگر مهاجرت برگشت‌ناپذیر نمایش لازم برای v1 را نابود کرده باشد، برگشت هندلر کمکی نمی‌کند.
کی API-محور ترتیب غلط است
نمونه آخرهفته با یک مصرف‌کننده کنار دست میتواند کد-محور باشد. وقتی تیم دوم یا بیلد موبایل به شکل وابسته شد قرارداد را منجمد کنید. منتظر استخدام سکویی نمانید.
کد اکتشافی داخلی که پیش از وابستگی فرایند دیگر کنار گذاشته می‌شود به وعده سازگاری عمومی نیاز ندارد. مرز وابستگی است نه اندازه شرکت: نقطه مونولیتی که یک کلاینت منتشرشده مصرف می‌کند همین حالا قرارداد دارد. ریزخدمات برای رویکرد API لازم نیست.
پرسش‌های پرتکرار
آیا برای API-محور بودن ریزخدمات لازم است؟
خیر. قرارداد بازبینیشده لازم است. مونولیت ماژولار میتواند API-محور باشد.
OpenAPI یا GraphQL؟
آنکه مصرفکنندهها بتوانند منجمد کنند. GraphQL همچنان نسخه و سیاست تغییر شکننده میخواهد.
کی نسخه URL را بالا ببرم؟
روی تغییر شکنندهای که نتوان پنهان کرد. نه روی هر کامیت.
تمرین برگشت چیست؟
آخرین شِمای OpenAPI را برگردانید، آخرین هندلرها را دوباره مستقر کنید، پنجره را به مصرف‌کننده بگویید.
پاسخ پرسش‌هایی که معمولاً در این موضوع بی‌جواب می‌مانند.
منابع این مقاله
هر آمار «رویکرد API یعنی قرارداد پیش از کد منتشر می‌شود» منبع دارد. جایی که عدد برآورد است نه سرشماری، در توضیح آمده است.
- روی فیلدینگ، رساله RESTقیود معماری برای API منبع.
- ابتکار OpenAPIخط مشخصات فعلی برای APIهای HTTP.
- پیشنهادهای بهبود API گوگلقواعد عملی نسخه‌بندی و سازگاری.
- راهنمای REST مایکروسافتسازگاری و قرارداد شکل خطا.
منابع اصلی این نسخه.
جمع‌بندی
قرارداد را منتشر کنید، شکست را نسخه بزنید، مشخصات هفته قبل را در ران‌بوک نگه دارید.
اگر بعد از رویکرد API یعنی قرارداد پیش از کد منتشر می‌شود تصمیم‌های هم‌جوار را می‌خواهید، از الگوهای معماری، ریزخدمات، برنامه مقیاس، دواپس شروع کنید.
