طراحی REST API از صفر تا مقاوم در برابر همه‌چیز

طراحی API خوب نامرئی است: مشتری‌ها بدون درد کارشان راه می‌افتد. طراحی بد، کارخانه‌ی تیکت پشتیبانی می‌سازد. این کتابچه است.

اسم‌ها اسم باشند، نه فعل

GET    /posts        # لیست
POST   /posts        # ساخت
GET    /posts/{id}   # خواندن
PATCH  /posts/{id}   # ویرایش جزیی
DELETE /posts/{id}   # حذف

کد وضعیتی که معنا دارد

• 200 موفق، 201 ساخته‌شد (با هدر Location)
• 400 درخواست خراب، 401 احراز هویت نشده، 403 مجاز نیست
• 404 پیدا نشد، 409 تناقض، 422 اعتبارسنجی شکست خورد
• 429 محدودیت نرخ، 503 موقتاً در دسترس نیست

صفحه‌بندی درست

{
  "data": [...],
  "meta": { "page": 2, "per_page": 20, "total": 143 }
}

برای داده‌های پرتغییر، cursor از offset بهتر است:

GET /posts?cursor=eyJpZCI6MzAwfQ&limit=20

خطاها هم قراردادند

{
  "error": {
    "code": "SLUG_TAKEN",
    "message": "پستی با این اسلاگ وجود دارد",
    "fields": { "slug": "باید یکتا باشد" }
  }
}

نسخه‌بندی

ترجیحاً سازگار جلو برو: هیچ‌وقت فیلدی را نشکن، فیلد جدید اضافه کن. اگر مجبور به شکستن شدی، در مسیر نسخه بده (/v2/posts)، نه در هدر.

قوانینی که از همه مهم‌ترند

API را از دید مصرف‌کننده طراحی کن. اگر فرانت برای رندر یک صفحه به سه درخواست پشت‌سرهم نیاز دارد، API باخته است.