چگونه یک HTTP Status Code حرفه‌ای برای API خود بنویسیم؟

چگونه یک HTTP Status Code حرفه‌ای برای API خود بنویسیم؟

وقتی پای نوشتن API برای یک سرویس تحت‌وب به‌میان می‌آید، بدون شک نیاز خواهیم داشت تا بسته به شرایط مختلف از کدهای وضعیت اچ‌تی‌تی‌پی (HTTP Status Codes) استفاده نماییم تا دیگر دولوپرهایی که از API ما استفاده می‌کنند تا حد ممکن کمتر سردرگم شوند. در همین راستا، یکسری Best Practice وجود دارند که با پیروی از آن‌ها، می‌توانیم اطمینان حاصل کنیم که Status Codeهایمان به‌خوبی قابل‌فهم خواهند بود.

به‌طورکلی، کدهای وضعیت در پروتکل HTTP به ۵ گروه زیر تقسیم‌بندی می‌شوند:

1xx
2xx
3xx
4xx
5xx

اما هرکدام از این سری کدها، خود حاوی زیرشاخه‌های بسیاری است؛ بنابراین اطمینان حاصل کردن از این‌که دیگر دولوپرهایی که به تعامل با APIمان می‌پردازند به‌خوبی قادر به درک معنا و مفهوم کدهای وضعیت هستند، امری ضروری است (مشاهدهٔ لیست HTTP Status Codes).

اهمیت کدهای وضعیت در این است که به‌منزلهٔ اولین نقطهٔ اتکایی هستند که اگر ریکوئست ارسال شده به سرور دچار مشکل شد، کلاینت را از این موضوع مطلع سازد.

کدهای وضعیت گروه 1xx
کدهای وضعیت HTTP که با عدد ۱ شروع می‌شوند حاوی ۲ کاربرد کلی هستند؛ اولین کاربرد به دیتای مرتبط با وضعیت کانکشن اشاره دارد. همچنین کدهای وضعیت گروه 1xx نشانگر رکوئست اولیه از طرف کلاینت هستند؛ به‌عبارت دیگر، کد وضعیت 100 (Continue) حاکی از آن است که سرور اطلاعات Request Headers را از کلاینت دریافت کرده و منتظر Request Body است.

کدهای وضعیت گروه 2xx
کدهای وضعیت HTTP که با عدد ۲ شروع می‌شوند نشان از موفقیت‌آمیز بودن ریکوئست ارسالی به سمت سرور دارند؛ به‌طورمثال، کد وضعیت 200 (OK) حاکی از آن است که ریکوئست باموفقیت انجام شده است و کد وضعیت 201 (Created) هم نشان می‌دهد که درخواست با موفقیت انجام شده و یک ریسورس جدید ایجاد گشته است.

کدهای وضعیت گروه 3xx
کدهای وضعیت HTTP که با عدد 3 شروع می‌شوند نشانگر این مسأله هستند که به‌منظور تکمیل موفقیت‌آمیز ریکوئست، کلاینت می‌بایست اقدام دیگری نیز انجام دهد؛ به‌عنوان‌مثال، کد وضعیت 301 (Moved Permanently) کلاینت را به URI متفاوتی برای عملی شدن درخواستش ارجاع می‌دهد.

کدهای وضعیت گروه 4xx
کدهای وضعیت HTTP که با عدد 4 شروع می‌شوند به‌نوعی برای کاربران غیرفنی نیز ملموس هستند چراکه معروف‌ترین کد وضعیت متعلق به این خانواده -۴۰۴ (Not Found)- برای بسیاری کاربران نام‌آشنا است! علاوه‌بر این، کدهای کاربردی دیگری نیز در این گروه قرار دارند که در طراحی APIها می‌توان از آن‌ها استفاده کرد که از آن جمله می‌توان به کد وضعیت 429 (Too Many Requests) اشاره کرد که در مواقعی می‌توان از آن استفاده کرد که تعداد ریکوئست‌های دریافتی از طرف کلاینتی خاص بیش از حد مجاز باشد که درنهایت منجر به رد درخواست توسط سرور می‌شود.

کدهای وضعیت گروه 5xx
کدهای وضعیت HTTP که با عدد 5 شروع می‌شوند در یک کلام همگی مرتبط با مشکلات سمت سرور بوده و اصلاً ربطی به کلاینت ندارند؛ برخلاف کدهای خانوادهٔ 4xx، کدهای وضعیت گروه 5xx زمانی مورد استفاده قرار می‌گیرند که در سمت سروری که API روی آن پیاده‌سازی شده است مشکلی بوجود آمده و سرور از انجام درخواست کلاینت ناتوان است که یکی از معروف‌ترین آن‌ها کد وضعیت ۵۰۳ (Service Unavailable) است که زمانی‌هایی مورد استفاده قرار می‌‌گیرد که سرویس در دسترسی نباشد.

فیچرهای یک Status Code خوب چیست؟
یک کد وضعیت خوب نه‌تنها کلاینت را در جریان روند انجام کار قرار می‌دهد، بلکه به کلاینت دلیل یا دلایل رخداد یک رویداد خاص را نیز نشان می‌دهد. به‌طورکلی، زمانی می‌توانیم بگوییم یک کد وضعیت خوب در اختیار کلاینت قرار داده‌ایم که از ۳ ویژگی زیر برخوردار باشد:
- حاوی کد وضعیت -مثلاً ۲۰۰- و همچنین توضیحات خلاصه -مثلاً OK- باشد.
- حاوی توضیحات تکمیلی و جزئیات بیشتری در مورد فرایند بوده و به کلاینت ارائه دهد.
- حاوی متنی قابل‌فهم برای کاربران باشد که خلاصه‌ای از کد، وضعیت، جزئیات، دلایل مرتبط و راه‌کار پیشنهادی برای حل مشکل باشد.

برای درک بهتر نحوهٔ نوشتن یک Status Code خوب، در ادامه به توضیح در مورد ویژگی‌های فوق‌الذکر خواهیم پرداخت.

کدهای وضعیت استاندارد
استفاده از کدهای وضعیت استاندارد که در بالا ۵ گروه مختلف آن‌ها را بررسی کردیم، می‌تواند نقطهٔ شروع خوبی برای نوشتن کدهای وضعیت حرفه‌ای باشد؛ درواقع، وقتی که شما از خانوادهٔ کدهای وضعیت 4xx یا 5xx استفاده می‌کنید، کاربر خیلی سریع متوجه خواهد شد که مشکلی -خواه از سمت کلاینت و خواه از سمت سرور- وجود دارد.

ارائهٔ جزئیات
اگر کد وضعیتی همچون ۴۰۰ (Bad Request) را در اختیار کلاینت قرار دهیم، گرچه چنین کدی حاکی از وجود مشکلی از سمت کاربر است، اما به‌هیج‌وجه اطلاعات کافی و کاربردی در اختیار کاربر قرار نمی‌دهد تا وی بتوانند اقدام مقتضی را درنظر گیرد. در همین راستا، می‌بایست جزئیات بیشتری را در اختیار کاربر قرار دهیم چراکه عبارت Bad Request به‌معنی «درخواست بد» مفهومی کلی دارد و کلمهٔ «بد» کاملاً نسبی است و ضروری است که آن را از حالت نسبی بودن خارج سازیم و مفهومش را کاملاً گویا و قابل‌درک نماییم.

قابل‌فهم برای کاربران
گرچه کدهای وضعیت عددی برای سیستم به‌خوبی قابل‌درک هستند (مثلاًً می‌توانیم بااستفاده از دستورات شرطی چک کنیم که اگر به‌طورمثال کد وضعیت برابر با ۴۰۰ بود، فلان کار انجام شود)، اما ارائهٔ جزئیات قابل‌فهم برای انسان‌ها هم کمک به هرچه حرفه‌ای‌تر شدن کدهای وضعیت می‌کند.

حال اگر بخواهیم آنچه در بالا بدان اشاره شد را به‌صورت عملی مورد بررسی قرار دهیم، با کد وضعیتی همچون آنچه در ادامه خواهید دید مواجه خواهیم شد:

{
    "code": 429,
    "codeMessage": "Too Many Requests",
    "errorDetails": "There have been more HTTP requests that you`re allowed to send; To solve this problem, you have to upgrade you plan to Unlimited API Usage."   
}

درواقع، در کد وضعیت بالا از کلیدهایی تحت عناوین codeMessage ،code و errorDetails استفاده کرده‌ایم که حاوی اطلاعات مفیدی برای دولوپری است که از API استفاده می‌کند که در کنار یکدیگر تشکیل‌دهندهٔ ۳ ویژگی یک Status Code حرفه‌ای و قابل‌فهم هستند.

در تفسیر کد وضعیت فوق، بایستی بگوییم که کد ۴۲۹ و پیام استاندارد Too Many Requests حاکی از آنند که تعداد درخواست‌های ارسالی به سمت سرور بیش از حد مجاز بوده اند اما آنچه بیش از هرچیزی برای دولوپری که این پیام خطا را دریافت کرده کاربردی است، پیام مرتبط با کلید errorDetails است که به این نکته اشاره دارد که «تعداد درخواست‌های ارسالی بیش از حد مجاز است و برای رفع این‌ مشکل، شما می‌بایست پلن خود را به Unlimited (بدون محدودیت) ارتقاء دهید.» که به‌سادگی راه‌کار مورد نیاز را هم برای رفع مشکل به دولوپر ارائه می‌دهد.

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

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

منبع


بهزاد مرادی