API خوب چه ویژگی‌هایی دارد
API خوب آن است که مصرف‌کننده بتواند بدون خواندن کد سرور، رفتارش را حدس بزند.
نویسنده
تیم بایتیرا
تاریخ انتشار
۱۲ شهریور ۱۴۰۵
زمان مطالعه
1 دقیقه
خلاصه
API خوب آن است که مصرف‌کننده بتواند بدون خواندن کد سرور، رفتارش را حدس بزند.
API قراردادی است بین دو تیم که ممکن است هرگز با هم صحبت نکنند. کیفیتش با میزان سؤالی که ایجاد می‌کند سنجیده می‌شود.
پیش‌بینی‌پذیری
اگر /projects/ فهرست می‌دهد و /projects/{id}/ یک مورد، آنگاه /posts/ هم باید همین‌طور رفتار کند. ناهماهنگی در نام‌گذاری، مصرف‌کننده را مجبور به خواندن مستندات برای هر اندپوینت می‌کند.
کد وضعیت درست
بازگرداندن ۲۰۰ با بدنه‌ای که می‌گوید خطا رخ داده، رایج‌ترین اشتباه است. ۴۰۰ برای ورودی نامعتبر، ۴۰۱ برای احراز هویت نشده، ۴۰۳ برای مجاز نبودن، ۴۰۴ برای نبودن منبع. این تمایز به مصرف‌کننده اجازه می‌دهد بدون تحلیل متن، تصمیم بگیرد.
خطای قابل استفاده
پیام خطا باید بگوید کدام فیلد مشکل دارد و چرا. «درخواست نامعتبر» چیزی حل نمی‌کند. ساختار خطا هم باید ثابت باشد تا کلاینت بتواند یک‌بار برایش کد بنویسد.
صفحه‌بندی از روز اول
هر فهرستی که می‌تواند رشد کند باید از ابتدا صفحه‌بندی داشته باشد. افزودن آن بعداً یعنی شکستن قرارداد.
چیزی که نباید برگردد
فیلدهای داخلی، شناسه‌های ترتیبی که قابل شمارش‌اند و هر داده‌ای که مصرف‌کننده اجازه دیدنش را ندارد. جداسازی مدل داخلی از مدل خروجی — یعنی سریالایزر جداگانه — این را ساختاری حل می‌کند.
نسخه‌بندی
پیشوند نسخه در مسیر بگذارید حتی اگر امروز فکر می‌کنید هرگز لازم نمی‌شود. افزودن آن بعداً هزینه دارد؛ داشتنش از اول رایگان است.
مطالب مرتبط
بدهی فنی: کِی بپذیریم و کِی بپردازیم
بدهی فنی همیشه بد نیست. بد آن است که ندانیم چقدر بدهکاریم و بهره‌اش را کجا می‌پردازیم.
خواندنسرعت سایت: چه چیزی را واقعاً باید بهینه کرد
بیشتر تلاش‌های بهینه‌سازی صرف چیزهایی می‌شود که کاربر حس نمی‌کند. سه چیز است که حس می‌شود.
خواندنچرا استقرار با داکر دردسر کمتری دارد
«روی سیستم من کار می‌کرد» یک شوخی نیست؛ نشانه این است که محیط اجرا بخشی از پروژه نیست.
خواندن