چند سال تجربه خودم در طراحی و پیاده سازی REST API ها و کار در تیم‌های مختلف و با Legacy Code ها، خیلی پیش اومده که API هایی دیدم که خیلی از استانداردها دور بوده. با سرچ کردن درباره Best Practice ها و تجربه خودم یه لیست آماده کردم از نکاتی درباره طراحی REST API ها که اگه رعایت بشه انتقال کدها و استفاده از اونها رو راحت‌تر میکنه.
در URL ها بهتره از اسم استفاده کنید و از فعل استفاده نکنید. مثلا استفاده از /api/users/ بهتر از استفاده از /api/users/create/ هست.
در URL یا از اسم‌های مفرد یا اسم‌های جمع استفاده کنید. هر کدوم رو انتخاب می‌کنید مهم نیست ولی در تمام پروژه فقط از یکی استفاده کنید. مثلا یا /api/users/ رو انتخاب کنید یا /api/user/ ولی ثبات رو در انتخاب نام‌ها رعایت کنید
به جای استفاده از فعل در URL باید از متدهای مختلف HTTP استفاده کنید. مثلا:
متد GET: برای دریافت آیتم‌ها
متد POST: برای ساخت آیتم‌ها
متد UPDATE: برای آپدیت آیتم‌ها
متد DELETE: برای حذف آیتم‌ها
پروتکل HTTP متدهای GET, OPTIONS, HEAD, TRACE رو به نام متدهای امن معرفی میکنه که این متدها نباید بتونن وضعیت سرور رو تغییر بدن. از این متدها باید درست استفاده کنید.
رابطه‌ها باید از طریق زیر URL ها فراخوانی شوند. مثلا برای دریافت لیست عکس‌های یک کاربر باید یک URL مثل /api/users/{id}/photos/ داشته باشید.
ورژن‌بندی API یا باید در URL یا در HEADER های ریکوئست باشه. مثلا /api/v1/users/ ورژن‌بندی در URL داره.
فیلتر، sort و pagination باید فقط در ریکوئست‌های GET قابل دسترس باشه. مثلا:
Filter: /api/v1/users?name=Ali
Sort: /api/v1/users?order_by=name&order=desc
Pagination: /api/v1/users?page=1&per_page=10
احراز هویت کاربران بهتره با استفاده از JWT و احراز هویت سرویس‌های متصل به API با استفاده از API KEY انجام بشه.
از Status Code های HTTP و معنی اونها باید درست استفاده کنید. لیست کامل کدها در اینجا هست. مثلا:
