مانیتورینگ API: فراتر از کد وضعیت ۲۰۰ چی رو باید چک کرد.

APIی که 200 OK برمی‌گردونه هنوز ممکنه خراب باشه. شاید یه لیست خالی برگردونه، یه پیام خطا داخل JSON معتبر، داده‌ی کهنه از کش، یا هشت ثانیه طول بکشه تا جواب بده. مانیتورینگ خوب API چک می‌کنه پاسخ چی می‌گه، نه فقط اینکه پاسخی رسید.

نکته‌های کلیدی

• کد وضعیت، زمان پاسخ و بدنه‌ی پاسخ رو چک کنید؛ هر سه تا.
• روی فیلدهایی از JSON شرط بذارید که فقط وقتی API واقعاً کار می‌کنه مقدار درست دارن.
• endpointهای نیازمند احراز هویت رو با یه حساب تست اختصاصی و کم‌دسترسی مانیتور کنید.
• برای جریان‌هایی که یه درخواست به درخواست قبلی وابسته است (ورود و بعد گرفتن داده) از چک چندمرحله‌ای استفاده کنید.
• درخواست‌های مانیتورینگ رو فقط‌خواندنی نگه دارید یا بعدش پاکسازی کنید.

سطح ۱: جواب می‌ده؟

حداقل چک یه درخواست می‌فرسته و یه کد وضعیت مشخص انتظار داره:

curl -s -o /dev/null -w "%{http_code} %{time_total}\n" https://api.example.com/v1/health
200 0.142

این چک سرورهای کرش‌کرده، دیپلوی‌های خرابی که 502 برمی‌گردونن و گواهی‌های منقضی رو پیدا می‌کنه. هر چیزی که «مؤدبانه» خراب بشه رو نمی‌بینه.

سطح ۲: به اندازه‌ی کافی سریعه؟

یه حد زمان پاسخ بذارید که با تحمل کلاینت‌ها جور باشه. اگه اپ موبایلتون بعد از ۱۰ ثانیه timeout می‌شه، هشدار در ۳ ثانیه برای واکنش جا می‌ذاره. روند رو هم دنبال کنید: endpointی که طی یه هفته از ۱۵۰ میلی‌ثانیه به ۹۰۰ میلی‌ثانیه می‌رسه معمولاً یه کوئری در حال رشد یا یه ایندکس جاافتاده داره.

سطح ۳: جواب درسته؟

روی بدنه‌ی پاسخ شرط بذارید. برای APIهای JSON، فیلدهایی رو چک کنید که مقدارشون ثابت می‌کنه سیستم از سر تا ته کار می‌کنه:

{
  "status": "ok",
  "database": "connected",
  "queue_depth": 12,
  "version": "2.14.0"
}

شرط‌های کاربردی:

• status برابر ok؛ سرویس خودش رو سالم گزارش می‌کنه.
• database برابر connected؛ endpoint سلامت واقعاً دیتابیس رو تست کرده.
• queue_depth کمتر از یه حد؛ کارهای پس‌زمینه تلنبار نشدن.
• یه endpoint لیست حداقل یه آیتم برمی‌گردونه؛ کاتالوگ خالی برای یه فروشگاه یعنی قطعی.

هدرها رو هم چک کنید

Content-Type باید application/json باشه؛ صفحه‌ی خطای HTML از یه پراکسی معمولاً با کد 200 و text/html می‌رسه. هدرهای کش و CORS وقتی یه دیپلوی تغییرشون می‌ده کلاینت‌ها رو به شکل‌های عجیبی خراب می‌کنن.

endpointهای نیازمند احراز هویت

باارزش‌ترین endpointها معمولاً توکن لازم دارن. با یه حساب تست اختصاصی مانیتورشون کنید که:

• فقط دسترسی‌هایی رو داره که چک لازم داره (هر جا می‌شه فقط‌خواندنی)،
• هیچ داده‌ی واقعی مشتری نداره،
• از آمار و صورت‌حساب کنار گذاشته شده.

اطلاعات ورودش رو توی فیلدهای امن ابزار مانیتورینگ نگه دارید، نه توی query string آدرس که سر از لاگ‌ها درمیاره.

چک‌های چندمرحله‌ای

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

1. POST /auth/login؛ access_token رو از پاسخ بیرون بکش.
2. GET /v1/orders?limit=1 با Authorization: Bearer {token}؛ کد 200 و یه لیست غیرخالی انتظار داریم.
3. GET /v1/orders/{id} با شناسه‌ی مرحله‌ی ۲؛ همون شناسه باید برگرده.

وقتی مرحله‌ی ۱ شکست می‌خوره می‌دونید مشکل از احراز هویته؛ وقتی فقط مرحله‌ی ۳ خرابه، مشکل از endpoint جزئیاته.

نذارید مانیتورینگ خسارت بزنه

• درخواست GET رو ترجیح بدید. اگه مجبورید نوشتن رو تست کنید، از sandbox یا یه رکورد تستی استفاده کنید که هر اجرا بازنویسیش کنه.
• فاصله‌ی منطقی بذارید؛ یه چک هر ۳۰ ثانیه یعنی حدود ۲۹۰۰ درخواست در روز، پس سمت endpointی نفرستیدش که پیامک می‌فرسته یا کارت شارژ می‌کنه.
• یه User-Agent قابل تشخیص بذارید تا تیم بتونه ترافیک مانیتورینگ رو از لاگ و آمار جدا کنه.

روی چی هشدار بدیم؟

پرسش‌های پرتکرار

• endpoint /health رو مانیتور کنم یا endpointهای واقعی رو؟

  +

  هر دو. endpoint سلامت می‌گه سرویس فکر می‌کنه حالش خوبه؛ endpoint واقعی ثابت می‌کنه کاربرها واقعاً داده می‌گیرن. endpointهای سلامتی که به دیتابیس دست نمی‌زنن راحت گول می‌خورن.

• APIها رو هر چند وقت یه بار چک کنیم؟

  +

  برای بیشتر APIها هر ۱ تا ۵ دقیقه، و برای APIهای پرداخت یا ورود که چند دقیقه قطعی گرون تموم می‌شه، هر ۳۰ تا ۶۰ ثانیه.

• می‌شه APIهای GraphQL یا SOAP رو هم مانیتور کرد؟

  +

  بله. کوئری رو به‌شکل بدنه‌ی POST بفرستید و روی فیلدهای پاسخ شرط بذارید؛ دقیقاً مثل REST.