طراحی REST API به نظر ساده میاد، اما نکات ریز و مهمی داره که باید رعایت کنیم. معمولا اشتباهاتی در طراحی API مرتکب میشیم که شامل این 5 مورده:
1️⃣ استفاده از فعل در آدرس URL
آدرس باید فقط «منبع» (اسم) باشه، نه «عمل» (فعل). عمل رو خود متد HTTP مشخص میکنه.
❌ GET /getAllBooks
❌ POST /createNewBook
✅ GET /books
✅ POST /books
2️⃣ استفاده نادرست از متدهای HTTP
متد درست باعث میشه API خودبهخود قابل فهم باشه:
GET گرفتن داده
POST ساختن منبع جدید
PUT جایگزینی کامل یک منبع
PATCH ویرایش جزئی یک منبع
DELETE حذف منبع
3️⃣ برنگردوندن کد وضعیت مناسب
کلاینت نباید مجبور بشه بدنه پاسخ رو پارس کنه تا بفهمه چی شده.
❌ همیشه 200 OK برگردوندن
✅200 OK برای GET و PUT موفق
✅201 Created وقتی با POST منبع جدید ساخته شد
✅204 No Content وقتی با DELETE چیزی حذف شد
✅404 Not Found وقتی منبع پیدا نشد
✅400, 401, 403, 429, 500 و … در مواقع لازم
4️⃣ نامگذاری ناسازگار
همه جا یک شکل باشه
❌ گاهی /book/123 گاهی /authors
✅ همیشه جمع بساز: /books/123 ، /authors ، /orders
5️⃣ فراموش کردن صفحهبندی (Pagination)
برگردوندن همه رکوردها در یک درخواست دروافع فاجعه عملکردیه
❌ برگردوندن ۱۰۰ هزار رکورد یهجا
✅ همیشه صفحهبندی داشته باش:
?page=3&limit=50
