REST API، خطا و Rate Limit

چرا این درس مهم است

API را با endpoint روشن، مدیریت خطا و محدودیت ارسال مصرف می‌کنی.

در IoT، «کار کرد» کافی نیست؛ اتصال، تاخیر، قطع و وصل، کیفیت داده و رفتار بعد از خطا بخشی از خود طراحی‌اند.

این درس مرحله اتصال و پایداری است: باید نشان بدهی گره ESP32، شبکه و سرویس مقصد فقط در حالت ایده‌آل کار نمی‌کند و در خطا هم قابل عیب‌یابی است.

نکته‌های فنی

• HTTP مدل Request/Response دارد و Method، URL، Header و Body اجزای اصلی درخواست‌اند.
• کدهای 2xx معمولا موفقیت، 4xx خطای درخواست و 5xx خطای سمت سرویس را نشان می‌دهند.
• JSON یک قالب رایج تبادل داده است ولی Schema و اعتبارسنجی داده همچنان لازم‌اند.
• برای دستگاه واقعی Timeout، Retry محدود و TLS در ارتباط حساس باید در طراحی دیده شوند.

این نکته‌ها را برای گره ESP32، شبکه و سرویس مقصد به یک زنجیره علت و معلول وصل کن: هر انتخاب باید یک اثر قابل مشاهده یا اندازه‌گیری داشته باشد. اگر نمی‌توانی بگویی با تغییر این تصمیم دقیقا کدام خروجی عوض می‌شود، هنوز طراحی را به اندازه کافی روشن نکرده‌ای.

مدل ذهنی

Sensor → ESP32 → Network → Service → Dashboard

در تحلیل REST API، خطا و Rate Limit مرزهای سیستم را روشن نگه دار. هر جا داده یا انرژی از یک بخش به بخش دیگر می‌رود، یک نقطه مناسب برای مشاهده، Log یا اندازه‌گیری داری.

سناریوی عملی

در یک تمرین «HTTP و API»، API را با endpoint روشن، مدیریت خطا و محدودیت ارسال مصرف می‌کنی. سپس نتیجه را با یک معیار عددی یا چک‌لیست مقایسه کن.

این درس مرحله اتصال و پایداری است: باید نشان بدهی گره ESP32، شبکه و سرویس مقصد فقط در حالت ایده‌آل کار نمی‌کند و در خطا هم قابل عیب‌یابی است.

روش تست پیشنهادی

معیار اصلی این درس: نرخ موفقیت درخواست، زمان پاسخ و رفتار سیستم هنگام Timeout/5xx.

1. یک Failure Mode واقعی یا شبیه‌سازی‌شده انتخاب کن.
2. قبل و بعد از خطا نرخ موفقیت درخواست، زمان پاسخ و رفتار سیستم هنگام Timeout/5xx را ثبت کن.
3. Recovery را هم تست کن؛ برگشتن سیستم به حالت سالم بخشی از معیار قبولی است.

نتیجه تست را با نسخه کد/مدار، شرایط محیط و تنظیمات مهم ثبت کن؛ بدون این اطلاعات مقایسه دو Run ممکن است گمراه‌کننده باشد.

عیب‌یابی مرحله‌ای

1. Status code، زمان پاسخ و Body را لاگ کن و سه حالت موفق، Timeout و پاسخ خطا را جدا تست کن.
2. فقط یک فرض را در هر مرحله تغییر بده؛ تغییر همزمان چند چیز نتیجه را مبهم می‌کند.
3. بعد از هر تغییر دوباره نرخ موفقیت درخواست، زمان پاسخ و رفتار سیستم هنگام Timeout/5xx را بگیر و نتیجه را با Baseline مقایسه کن.

اگر علامت خطا عوض شد، آن را به عنوان داده جدید ببین؛ عوض شدن علامت همیشه به معنی حل شدن علت اصلی نیست.

دام رایج

اگر یک درخواست یک بار جواب داد به معنی مقاوم بودن سیستم نیست؛ قطع شبکه، پاسخ ناقص و خطای سرور باید مدیریت شوند.

برای رد یا تایید این برداشت، یک تست مرزی طراحی کن که دقیقا همین فرض را هدف بگیرد.

تمرین عملی

Disconnect، Timeout یا Restart را عمدا ایجاد کن و ببین سیستم بدون دخالت دستی چطور بازیابی می‌شود.

تمرین را برای REST API، خطا و Rate Limit انجام بده و در پایان فقط سه چیز تحویل بده: شرایط شروع، نتیجه اندازه‌گیری‌شده و تصمیم بعدی. اگر نتیجه با انتظار فرق داشت، یک فرض برای علت بنویس و تست بعدی را مشخص کن.

قبل از رفتن به درس بعد

• بتوانی «REST API، خطا و Rate Limit» را با زبان خودت توضیح بدهی و نقش آن را در یک سیستم واقعی مشخص کنی.
• بتوانی یک تصمیم طراحی مرتبط با این موضوع را با دلیل فنی انتخاب کنی.
• بتوانی یک خطای رایج را مرحله‌ای عیب‌یابی کنی و نتیجه را با نرخ موفقیت درخواست، زمان پاسخ و رفتار سیستم هنگام Timeout/5xx بسنجی.

اگر یکی از این موارد را فقط می‌توانی تعریف کنی ولی نمی‌توانی روی یک مثال واقعی نشان بدهی، همان بخش را یک بار دیگر با داده یا Log مرور کن.

جمع‌بندی

در REST API، خطا و Rate Limit هدف نهایی حفظ اصطلاحات نیست؛ باید بتوانی یک تصمیم فنی بگیری، اثرش را با نرخ موفقیت درخواست، زمان پاسخ و رفتار سیستم هنگام Timeout/5xx بسنجی و وقتی نتیجه خراب شد مسیر عیب‌یابی قابل تکراری داشته باشی. این سه توانایی معیار عبور واقعی از درس‌اند.