بهترین شیوه‌های طراحی API: ساخت رابطی که توسعه‌دهندگان دوستش دارند

یک API خوب مثل یک رابط کاربری خوب است؛ کاربر (که اینجا توسعه‌دهنده دیگری است) باید بتواند بدون خواندن مستندات طولانی، رفتار آن را حدس بزند. طراحی API حرفه‌ای، تفاوت بین یک سرویس محبوب و یک منبع سردرگمی است.

اصل اول: پیش‌بینی‌پذیری

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

بهترین API آن است که توسعه‌دهنده برای استفاده از آن نیازی به فکر کردن نداشته باشد.

نام‌گذاری منابع

در REST، endpointها باید منابع را با اسم جمع نشان دهند، نه افعال:

GET    /courses          فهرست دوره‌ها
GET    /courses/42       جزئیات یک دوره
POST   /courses          ساخت دوره جدید
PUT    /courses/42       به‌روزرسانی دوره
DELETE /courses/42       حذف دوره

استفاده درست از کدهای وضعیت HTTP

کدهای وضعیت زبان مشترک API و کلاینت هستند. از آن‌ها درست استفاده کنید:

• 200 برای موفقیت، 201 برای ساخت موفق منبع.
• 400 برای درخواست نامعتبر، 401 و 403 برای مشکلات احراز هویت و دسترسی.
• 404 برای منبع یافت‌نشده، 500 برای خطای سرور.

نسخه‌بندی و مدیریت خطا

نسخه‌بندی

API شما با گذر زمان تغییر می‌کند. با قرار دادن نسخه در مسیر (مثل /api/v1/) از همان ابتدا، می‌توانید تغییرات آینده را بدون شکستن کلاینت‌های فعلی اعمال کنید.

پیام‌های خطای واضح

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

صفحه‌بندی و فیلتر از روز اول

وقتی فهرستی برمی‌گردانید، از همان ابتدا pagination و filtering را در نظر بگیرید. اضافه کردن این‌ها بعداً، تغییرات شکننده‌ای ایجاد می‌کند که کلاینت‌های موجود را خراب می‌کند.

جمع‌بندی

طراحی API خوب نیازمند تفکر از دیدگاه مصرف‌کننده است. با یکنواختی، نام‌گذاری درست منابع، استفاده صحیح از کدهای HTTP، نسخه‌بندی و مستندسازی به‌روز، می‌توانید APIای بسازید که توسعه‌دهندگان از کار با آن لذت ببرند.