الگو
یک بازار بزرگ ابزارهای فروشنده را به روی عامل‌های بیرونی باز کرده است، که با یک ارائه‌دهنده مدل واحد آغاز می‌شود. پلتفرم‌های رزرو، تجارت و مالیات نیز با سطوح عامل‌محور خود در حال پیگیری هستند. این یک کلاس رابط جدید است: مصرف‌کننده اصلی یک برنامه‌ریز است، نه یک شخص با مرورگر. این تمایز ظاهری نیست. یک انسان می‌تواند پیش‌شرط‌های گمشده را از زمینه استنتاج کند، خطاهای مبهم را تحمل کند و یک اقدام ناموفق را دستی دوباره امتحان کند. یک برنامه‌ریز نمی‌تواند. او نیاز دارد که قرارداد صریح، قطعی و قابل‌خواندن برای ماشین باشد.
آنچه فراخوان‌های ماشینی نیاز دارند و APIهای انسانی از آن غافلند
بیشتر APIهای عمومی برای توسعه‌دهندگانی طراحی شده‌اند که علیه آن‌ها کد می‌نویسند، اما مصرف‌کننده زمان اجرا هنوز انسانی است که مستندات را می‌خواند، پاسخ‌ها را بررسی می‌کند و منطق دفاعی می‌نویسد. فراخوان‌های عامل آن انسان را از حلقه حذف می‌کنند. آن‌ها به سه چیز نیاز دارند که اغلب گم شده است.
پیش‌شرط‌های قابل‌خواندن برای ماشین
اینکه کدام فیلدها برای کدام انتقال‌های حالت لازم است باید به صورت یک schema بیان شود، نه به صورت متن. برای مثال، یک endpoint رزرو ممکن است guest_count را فقط زمانی لازم داشته باشد که status برابر confirmed است، یا tax_id را فقط برای رزروهای تجاری. اگر این در یک پاراگراف دفن شده باشد، یک برنامه‌ریز حدس خواهد زد. یک ماشین حالت با فیلدهای لازم برای هر انتقال، مقادیر مجاز و اثرات جانبی منتشر کنید. JSON Schema یا یک توصیف رسمی معادل اختیاری نیست؛ خود رابط است.
طبقه‌بندی قطعی خطا
خطاها باید بر اساس کد طبقه‌بندی شوند، نه بر اساس پیام. یک برنامه‌ریز نیاز دارد که تمایز دهد:
- قابل تلاش مجدد: خرابی شبکه گذرا، محدودیت نرخ، رقابت قفل. عامل می‌تواند عقب‌نشینی کند و دوباره تلاش کند.
- پایانی: ورودی نامعتبر، مجوز گمشده، انتقال حالت پشتیبانی‌نشده. تلاش مجدد کمکی نمی‌کند.
- نیاز به انسان: قاعده تجاری مبهم، بازبینی دستی لازم، اختلاف. عامل باید ارجاع دهد.
اگر تنها سیگنال یک پیام متن آزاد باشد، برنامه‌ریز باید یا تطبیق رشته‌ای شکننده را هاردکد کند یا تسلیم شود. هر دو شکست هستند. یک مجموعه کد خطای پایدار با نگاشت مستند به این سه کلاس منتشر کنید، و کلاس را در بدنه پاسخ بگنجانید تا بدون جدول جستجو قابل تجزیه باشد.
کلیدهای Idempotency روی هر فراخوان تغییردهنده
یک برنامه‌ریز ممکن است یک مرحله را پس از یک timeout، یک خرابی یا یک شکست جزئی دوباره تلاش کند. بدون یک کلید idempotency، یک POST /bookings دوباره تلاش‌شده می‌تواند دو بار رزرو یا دو بار شارژ کند. کلید باید توسط کلاینت تولید شود، برای هر عملیات منطقی یکتا باشد، و توسط سرور برای یک پنجره تعریف‌شده رعایت شود. سرور باید برای یک کلید تکراری همان پاسخ را برگرداند، نه یک منبع جدید. این ایده جدیدی نیست، اما به‌طور ناهمگون اعمال می‌شود. برای سطوح عامل‌محور، روی هر فراخوان تغییردهنده اجباری است، از جمله لغوها و بازپرداخت‌ها.
سهمیه‌ها به عنوان بخشی از قرارداد
محدودیت‌های نرخ اغلب یک فکر بعدی عملیاتی هستند. برای فراخوان‌های عامل، آن‌ها بخشی از رابط هستند. محدودیت‌های نرخ و مجوزهای انفجاری را در سند کشف منتشر کنید تا برنامه‌ریزها بتوانند زمان‌بندی کنند. هدرهای سهمیه باقی‌مانده را برگردانید تا یک عامل بتواند پیش از شکست عقب‌نشینی کند. مسیرهای تعاملی و دسته‌ای را جدا کنید؛ عاملی که تطبیق انجام می‌دهد نباید با یک تسویه رقابت کند.
یک مکانیزم مشخص: یک endpoint GET /limits را افشا کنید که سهمیه‌های فعلی، پنجره‌های انفجاری و زمان‌های بازنشانی را در قالبی قابل‌خواندن برای ماشین برگرداند. X-RateLimit-Remaining و X-RateLimit-Reset را روی هر پاسخ بگنجانید. یک برنامه‌ریز سپس می‌تواند یک زمان‌بند سطل توکن پیاده‌سازی کند که محدودیت‌های
معاوضه: نگهداری مسیرهای جداگانه پیچیدگی عملیاتی اضافه می‌کند و می‌تواند به ظرفیت کم‌استفاده در مسیر دسته‌ای در دوره‌های اوج تعاملی منجر شود. جایگزین—یک مسیر واحد با اشاره‌های اولویت—ساده‌تر برای عملیات است اما برای یک برنامه‌ریز سخت‌تر برای استدلال، زیرا اولویت یک تضمین نیست. انتخاب صادقانه بستگی دارد به اینکه آیا پلتفرم می‌تواند گرسنگی گاه‌به‌گاه کار دسته‌ای را تحمل کند.
پیامدهای حاکمیتی
هر endpoint عامل‌محور نیاز به یک مالک، یک سیاست منسوخ‌سازی و یک تغییرنگار نسخه‌بندی‌شده دارد. تغییرات شکننده در یک رابط عامل را به عنوان یک حادثه تولیدی برای سیستم‌های پایین‌دستی در نظر بگیرید. برخلاف یک تغییر UI انسانی، یک عامل نمی‌تواند با خواندن یک بنر سازگار شود. او بی‌صدا شکست خواهد خورد یا، بدتر، یک اقدام اشتباه انجام می‌دهد.
یک گزارش درخواست قابل بازپخش نگه دارید تا اختلافات درباره آنچه یک عامل انجام داده از شواهد حل شود. گزارش باید شامل کلید idempotency، درخواست و پاسخ کامل، هویت عامل و مهر زمانی باشد. این فقط برای اشکال‌زدایی نیست؛ پایه اعتماد است. وقتی یک فروشنده ادعا می‌کند یک عامل یک اسلات را دو بار رزرو کرده، پلتفرم باید بتواند دقیقاً نشان دهد چه چیزی درخواست شده و چه چیزی برگردانده شده است.
یادداشتی درباره کشف
سطوح عامل‌محور باید بدون مداخله انسانی قابل کشف باشند. یک مانیفست قابل‌خواندن برای ماشین در یک مسیر شناخته‌شده (مثلاً /.well-known/agent-api) که endpointها، schemaها، کدهای خطا، محدودیت‌های نرخ و روش‌های احراز هویت را فهرست می‌کند، حداقل است. این معادل عامل یک sitemap است. بدون آن، هر یکپارچه‌سازی سفارشی است.
نتیجه‌گیری
طراحی ابتدا برای فراخوان‌های ماشینی به معنای نادیده گرفتن توسعه‌دهندگان انسانی نیست. به این معناست که قرارداد را به اندازه کافی صریح کنیم تا یک برنامه‌ریز بتواند بدون حدس زدن درباره آن استدلال کند. Idempotency، سهمیه‌ها و معناشناسی خطا ویژگی نیستند؛ آن‌ها رابط هستند. پلتفرم‌هایی که آن‌ها را به عنوان فکر بعدی در نظر می‌گیرند، خواهند دید که عامل‌ها به روش‌هایی شکست می‌خورند که اشکال‌زدایی سخت و اعتماد سخت‌تر است. آن‌هایی که آن‌ها را به عنوان بخشی از قرارداد منتشر می‌کنند، یک کلاس جدید از اتوماسیون را ممکن می‌سازند که قابل اعتماد، قابل حسابرسی و ایمن برای تلاش مجدد است.