📕 کتاب REST API Design Rulebook

📌 فصل سوم: Interaction Design with HTTP

📍پارت: دوم

#کتاب

💎 استاتوس کدهای ریسپانس (Response Status Codes) 💎

‏REST API‌ ها از قسمت Status-Line توی ریسپانس HTTP استفاده می‌کنن تا به کلاینت‌ها نتیجه درخواستشون رو اعلام کنن. استاندارد RFC 2616، ساختار Status-Line رو به این شکل تعریف کرده:

Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase CRLF

‏HTTP حدود ۴۰ تا کد وضعیت استاندارد داره که برای بیان نتیجه درخواست‌های کلاینت استفاده میشه. این کدها به ۵ دسته اصلی تقسیم می‌شن که توی جدول زیر توضیح دادم:

⭕️ دسته‌بندی کدهای وضعیت:

1. 1xx: اطلاعاتی – اطلاعاتی در مورد سطح پروتکل انتقال میده.
2. 2xx: موفقیت‌آمیز – درخواست کلاینت با موفقیت قبول شده.
3. 3xx: تغییر مسیر – کلاینت باید یه کار اضافی انجام بده تا درخواست کامل بشه.
4. 4xx: خطای کلاینت – خطاهای این دسته مربوط به اشتباهات کلاینت هست.
5. 5xx: خطای سرور – سرور مسئولیت این خطاها رو قبول می‌کنه.

⭕️ قوانین استفاده از کدهای وضعیت:

⭕️ کد 200 (OK): برای موفقیت کلی
این کد معمولاً همون چیزیه که کلاینت انتظار داره ببینه. یعنی درخواست با موفقیت انجام شده و نیازی به استفاده از کد خاص دیگه‌ای از سری ۲xx نیست. برعکس کد 204، وقتی 200 برگرده، باید یه بدنه پاسخ (response body) هم داشته باشه.

⭕️ کد 200 (OK) نباید برای اعلام خطا استفاده بشه
همیشه باید از کدهای وضعیت HTTP درست استفاده کنید. به‌خصوص، نباید برای سازگار شدن با کلاینت‌های ساده‌تر از قواعد استاندارد API صرف‌نظر کرد.

⭕️ کد 201 (Created): برای ایجاد موفقیت‌آمیز منابع جدید
هر وقت که یه API یه منبع جدید برای درخواست کلاینت ایجاد می‌کنه (مثلاً توی یه کالکشن یا فروشگاه)، باید از کد 201 استفاده کنه. حتی اگر منبع جدید از طریق یه عمل کنترلر ایجاد بشه، باز هم 201 کد درستی برای پاسخ هست.

⭕️ کد 202 ("Accepted") باید برای شروع موفقیت‌آمیز یک عملیات غیرهمزمان استفاده بشه
کد 202 یعنی درخواست کلاینت قراره به صورت غیرهمزمان (آسنکرون) پردازش بشه. این کد به کلاینت میگه که درخواستش معتبر به نظر می‌رسه، اما ممکنه بعداً موقع پردازش به مشکل بخوره. این کد معمولاً برای عملیات‌هایی که زمان زیادی می‌برن استفاده می‌شه.
کنترلرها می‌تونن 202 رو برگردونن، اما منابع دیگه نباید این کار رو بکنن.

⭕️ کد 204 ("No Content") باید زمانی استفاده بشه که بدنه پاسخ (response body) خالیه
کد 204 معمولاً وقتی استفاده میشه که API به درخواست‌های PUT، POST یا DELETE پاسخ میده ولی قصد نداره که توی پاسخ، پیام یا داده‌ای برگردونه.
حتی در پاسخ به درخواست GET هم میشه از 204 استفاده کرد تا بگه منبع درخواست‌شده وجود داره، ولی چیزی برای نمایش نداره.

⭕️ کد 301 ("Moved Permanently") برای تغییر مکان دائمی منابع استفاده بشه
- کد 301 وقتی استفاده میشه که مدل منابع توی API تغییر بزرگی کرده و یه آدرس جدید برای منبع به کلاینت اختصاص داده شده. توی این حالت، آدرس جدید باید توی هدر "Location" به کلاینت اعلام بشه.

⭕️ از کد 302 ("Found") نباید استفاده بشه
کد 302 همیشه اشتباه فهمیده شده و برنامه‌نویسا توی پیاده‌سازیش اشتباه کردن. مشکل اصلی اینجاست که کلاینت‌ها به‌طور خودکار برای آدرس جدید یه درخواست GET می‌فرستن، حتی اگر روش اصلی درخواست چیز دیگه‌ای بوده.
برای رفع این مشکل، توی HTTP 1.1 کدهای 303 ("See Other") و 307 ("Temporary Redirect") معرفی شدن که به جای 302 باید استفاده بشن.

⭕️ کد 303 ("See Other") باید برای ارجاع کلاینت به یه URI دیگه استفاده بشه
وقتی یه کنترلر کارش رو تموم کرده، به جای فرستادن پاسخ توی بدنه‌ای که شاید کلاینت نمی‌خواد، می‌تونه با کد 303 یه URI جدید به کلاینت بده. این URI می‌تونه به یه پیام موقت یا یه منبع دائمی‌تر اشاره کنه.
این کد به API اجازه میده که به جای تحمیل دانلود اطلاعات به کلاینت، یه مرجع به منبع بده و کلاینت اگه بخواد می‌تونه با GET به URI جدید دسترسی پیدا کنه.

⭕️ کد 304 ("Not Modified") باید برای صرفه‌جویی در پهنای باند استفاده بشه
این کد شبیه کد 204 ("No Content") هست چون هیچ چیزی توی بدنه پاسخ نیست، اما تفاوت اصلی اینه که 204 وقتی استفاده می‌شه که هیچ داده‌ای برای فرستادن وجود نداره، ولی 304 وقتی استفاده میشه که منبع اطلاعات داره اما کلاینت قبلاً آخرین نسخه‌اش رو گرفته.
این کد بیشتر توی درخواست‌های HTTP شرطی (conditional requests) کاربرد داره.

@ninja_learn_ir