طراحی API برای ایجنتها برعکس طراحی برای آدمهاست
هوش مصنوعیخلاصهٔ کاملتر
نویسندهٔ این پست که تو Freestyle کار میکنه میگه تو دو سال اخیر نظرش دربارهٔ طراحی API صد و هشتاد درجه چرخیده. دلیلش هم سادهست: بیشتر کسایی که امروز یه API رو مصرف میکنن آدم نیستن، کدیه که یه ایجنت نوشته. به گفتهٔ نویسنده همین جابهجایی مخاطب، خیلی از قاعدههای قدیمی رو بیاثر کرده.
تو طراحی برای آدم، هدف اینه که کاربر تو پنجاه خط کد به یه چیز کارراهانداز برسه و لازم نباشه از بیست فیلد، نوزده تای دیگه رو بشناسه. نویسنده Stripe و Twilio رو مثال میزنه: نوجوون که بوده تونسته باهاشون کار کنه بدون اینکه بدونه ACH چیه یا Stripe چند ده کار دیگه هم بلده.
ولی ایجنت کل مستندات رو تو یه نشست میخونه و تو چند ثانیه هزار خط کد تولید میکنه. نویسنده میگه تو این وضعیت گلوگاه دیگه «یاد گرفتن» نیست، «فهمیدن اینکه کد دقیقاً چی کار میکنه» ـه — و دیباگ همونجا سخت میشه. برای همین از نظر او وضوح مهمترین ویژگی یه API شده.
اولین نتیجهگیریاش اینه که مقدارهای پیشفرض بیشتر ضرر دارن تا فایده. ایجنت میتونه مستندات رو بخونه و همهٔ فیلدها رو صریح پر کنه، پس هزینهٔ صراحت تقریباً صفر شده در حالی که هزینهٔ ابهام بالا رفته. نویسنده میگه فیلدهای کماهمیتتر میتونن با یه توضیح از بقیه جدا بشن، ولی خالی موندنشون دیگه مزیت نیست.
دومی اینه که خطا لزوماً چیز بدی نیست. APIهایی که حروف بزرگ رو خودشون کوچیک میکنن یا چند مقدار مختلف رو برای یه معنی قبول میکنن، تو کدبیس ایجنتی باعث میشن هر تابع یهجور بنویسه و مرورکنندهٔ بعدی سردرگم بشه. به گفتهٔ نویسنده خطای خوب — خطایی که بگه چی اشتباه بوده و کجا رو باید خوند — برداشت غلط ایجنت رو همونجا اصلاح میکنه؛ خطای مبهم و بیجهت البته هنوز بده.
سومی سر اسمگذاریه. فیلدی مثل name تو هر API یه معنی داره؛ یه جا اسم نمایشی، یه جا شناسهٔ کامل. نویسنده میگه ایجنت تو ده کاربرد مختلف پنججور ازش استفاده میکنه و فقط یکیشون درسته، پس بهتره از اول اسم دقیق بذاری: displayName، slug یا externalId.
چهارمی اینه که ارزش یه API تو دوران ایجنتها همون «واقعیتی» ـه که خود ایجنت نمیتونه بسازه: پول پرداختشده، پیام فرستادهشده، ماشین مجازی بالا اومده. بقیهش رو میشه با راهنما جبران کرد. نویسنده میگه Freestyle هم پکیجها و لایههای انتزاعی SDKش رو حذف کرده و جاش راهنما گذاشته تا ایجنت خودش کد لازم رو دربیاره.
نکات کلیدی:
- مخاطب اصلی APIها عوض شده: کد ایجنتها، نه توسعهدهندهٔ انسانی
- مقدار پیشفرض و «هوشمندی» در پذیرش ورودی، تو کد ایجنتی ناسازگاری میسازه
- خطای دقیق و راهنمادار ابزار خوبیه، نه شکست در آنبوردینگ
- اسم فیلد هرچی مشخصتر، احتمال توهم و تفسیر غلط کمتر
- SDKهای پرابزار جای خودشون رو به مستندات و راهنما میدن
