مرجع نهایی برای کدهای وضعیت HTTP در طراحی API – انجمن DEV

در دنیای توسعه وب و طراحی API، کدهای وضعیت HTTP نقش مهمی در برقراری ارتباط نتیجه درخواست‌ها بین مشتریان و سرورها دارند. این کدها یک راه استاندارد برای نشان دادن شرایط خاص، موفقیت ها یا خطاهایی که در طول پردازش درخواست های HTTP رخ می دهند، ارائه می دهند. درک این کدهای وضعیت برای توسعه دهندگان ضروری است، زیرا به اشکال زدایی، مدیریت خطا و ایجاد برنامه های کاربردی قوی تر کمک می کند.

1. 1xx اطلاعاتی

این کدهای وضعیت نشان دهنده یک پاسخ موقت است. آنها به ندرت در عمل استفاده می شوند، اما می توانند در سناریوهای خاصی مفید باشند.

• 100 ادامه: سرور سرصفحه های درخواست را دریافت کرده است و کلاینت باید اقدام به ارسال بدنه درخواست کند.
• 101 پروتکل های سوئیچینگ: درخواست کننده از سرور خواسته است که پروتکل ها را تغییر دهد و سرور با این کار موافقت کرده است.

2. 2xx موفقیت

این کدهای وضعیت نشان می دهد که درخواست مشتری با موفقیت دریافت، درک و پذیرفته شده است.

• 200 باشه: درخواست با موفقیت انجام شد و پاسخ حاوی داده یا نتیجه درخواستی است.
  • مثال: بازیابی اطلاعات پروفایل کاربر.

• 201 ایجاد شد: درخواست با موفقیت انجام شد و یک منبع جدید ایجاد شد.

  • مثال: ایجاد یک حساب کاربری جدید یا ارسال یک ورودی جدید در وبلاگ.

• 204 بدون محتوا: سرور با موفقیت درخواست را پردازش کرد اما هیچ محتوایی را بر نمی گرداند.

  • مثال: به‌روزرسانی تنظیمات کاربر در جایی که نیازی به پاسخگویی نیست.

• 206 محتوای جزئی: سرور فقط بخشی از منبع را به دلیل هدر محدوده ارسال شده توسط مشتری ارائه می کند.

  • مثال: پخش جریانی محتوای ویدیویی یا دانلود فایل‌های بزرگ به صورت تکه‌ای.

3. تغییر مسیر 3xx

این کدهای وضعیت نشان می دهد که برای انجام درخواست باید اقدامات بیشتری توسط عامل کاربر انجام شود.

• 301 به طور دائم منتقل شد: منبع درخواستی برای همیشه به یک URL جدید منتقل شده است.
• 302 پیدا شد: منبع درخواستی به طور موقت تحت یک URL دیگر قرار دارد.
• 304 اصلاح نشده است: نشان می دهد که منبع از نسخه ای که توسط سرصفحه های درخواست مشخص شده است تغییر نکرده است.

4. خطای مشتری 4xx

این کدهای وضعیت برای موقعیت هایی در نظر گرفته شده اند که به نظر می رسد مشتری در آن اشتباه کرده است.

• 400 درخواست بد: سرور نمی تواند درخواست را به دلیل نحو نامعتبر یا ورودی بد پردازش کند.

  • مثال: ارسال JSON نادرست در بدنه درخواست.
  • استفاده: زمانی استفاده می شود که خود درخواست بدشکل باشد یا دارای پارامترهای نامعتبر باشد.

• 401 غیر مجاز: درخواست نیاز به احراز هویت کاربر دارد.

  • مثال: تلاش برای دسترسی به یک نقطه پایانی API محافظت شده بدون ارائه اعتبارنامه معتبر.
  • استفاده: زمانی استفاده می شود که احراز هویت مورد نیاز است و ارائه نشده است یا نامعتبر است.

• 403 ممنوع: سرور درخواست را درک می کند اما از تایید آن خودداری می کند.

  • مثال: کاربری که سعی می کند به ویژگی های فقط سرپرست دسترسی پیدا کند.
  • استفاده: زمانی استفاده می شود که کاربر احراز هویت شده است اما مجوز عملیات درخواستی را ندارد.

• 404 یافت نشد: منبع درخواستی در سرور یافت نشد.

  • مثال: تلاش برای بازیابی نمایه کاربری حذف شده.
  • استفاده: زمانی استفاده کنید که منبع درخواستی وجود نداشته باشد.

• روش 405 مجاز نیست: روش مشخص شده در درخواست برای منبع شناسایی شده توسط URI درخواست مجاز نیست.

  • مثال: ارسال یک درخواست POST به نقطه پایانی که فقط درخواست های GET را می پذیرد.

• 409 تعارض: به دلیل تضاد با وضعیت فعلی منبع، درخواست پردازش نشد.

  • مثال: تلاش برای ایجاد یک کاربر با ایمیلی که از قبل در سیستم وجود دارد.
  • استفاده: زمانی استفاده می شود که با وضعیت فعلی منبع تضاد دارد، مانند ورودی های تکراری.

• 422 موجودیت غیر قابل پردازش: سرور نوع محتوا و نحو درخواست را درک می کند، اما نمی تواند دستورالعمل های موجود را پردازش کند.

  • مثال: ارسال فرمی با داده های نامعتبر که اعتبار سنجی سمت سرور ناموفق است.
  • استفاده: برای خطاهای اعتبارسنجی که در آن نحو درخواست صحیح است، اما داده ها از نظر معنایی نادرست هستند، استفاده کنید.

• 429 درخواست خیلی زیاد: کاربر در مدت زمان معین درخواست های زیادی ارسال کرده است (“محدود کردن نرخ”).

  • مثال: اجرای محدودیت نرخ API برای جلوگیری از سوء استفاده.

5. خطای سرور 5xx

این کدهای وضعیت مواردی را نشان می دهد که در آن سرور آگاه است که با خطا مواجه شده است یا در غیر این صورت قادر به انجام درخواست نیست.

• 500 خطای سرور داخلی: یک پیام خطای عمومی که نشان می دهد سرور با شرایط غیرمنتظره ای مواجه شده است که مانع از انجام درخواست شده است.

  • مثال: یک استثنا کنترل نشده در کد سمت سرور رخ می دهد.

• 501 اجرا نشد: سرور از عملکرد مورد نیاز برای انجام درخواست پشتیبانی نمی کند.

  • مثال: استفاده از یک روش HTTP جدید که سرور آن را نمی شناسد.

• دروازه بد 502: سرور در حالی که به عنوان یک دروازه یا پروکسی عمل می کند، یک پاسخ نامعتبر از سرور بالادستی دریافت می کند.

  • مثال: یک سرور پروکسی معکوس نمی تواند به سرور مبدا متصل شود.

• سرویس 503 در دسترس نیست: سرور در حال حاضر به دلیل بارگذاری بیش از حد یا تعمیر موقت قادر به رسیدگی به درخواست نیست.

  • مثال: یک سرور تحت تعمیر و نگهداری برنامه ریزی شده است یا ترافیک بالایی را تجربه می کند.

• 504 Gateway Timeout: سرور در حالی که به عنوان یک دروازه یا پروکسی عمل می کند، پاسخی به موقع از سرور بالادستی دریافت نمی کند.

  • مثال: در زمان انتظار برای پاسخ از یک API شخص ثالث، مهلت زمانی رخ می دهد.

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

1. خاص باشید: از خاص ترین کد وضعیتی که در مورد موقعیت اعمال می شود استفاده کنید. این به مشتریان کمک می کند تا بفهمند دقیقاً چه اتفاقی افتاده و چگونه باید پاسخ دهند.

2. استفاده مداوم: سازگاری در نحوه استفاده از کدهای وضعیت در API خود را حفظ کنید. این کار توسعه‌دهندگان را آسان‌تر می‌کند تا با API شما کار کنند.

3. اطلاعات تکمیلی را ارائه دهید: در صورت لزوم همراه با کد وضعیت، یک پیام خطای دقیق در بدنه پاسخ قرار دهید. این می تواند به اشکال زدایی و بهبود تجربه توسعه دهنده کمک کند.

4. ملاحظات امنیتی: در مورد فاش کردن اطلاعات بیش از حد در پاسخ های خطا، به خصوص برای خطاهای 4xx و 5xx، محتاط باشید. از افشای جزئیات حساس در مورد معماری یا پیاده سازی سیستم خود اجتناب کنید.

5. مستندات: به وضوح مستند کنید که کدام کدهای وضعیت API شما و تحت چه شرایطی استفاده می کند. این به مصرف کنندگان API کمک می کند تا نحوه تفسیر و مدیریت پاسخ های مختلف را درک کنند.

با درک و اجرای صحیح کدهای وضعیت HTTP، توسعه‌دهندگان می‌توانند APIها و برنامه‌های کاربردی وب قوی‌تر، واضح‌تر و کاربرپسندتر ایجاد کنند. این کدها به عنوان یک ابزار ارتباطی حیاتی بین کلاینت‌ها و سرورها عمل می‌کنند و به ساده‌سازی مدیریت خطا و بهبود قابلیت اطمینان کلی سیستم کمک می‌کنند.