پایش API

چرا API به پایش اختصاصی نیاز دارد

API صرفاً یک صفحه در /api/ نیست. این یک قرارداد است. متد HTTP مهم است – تفاوت بین GET و POST معنای درخواست را تغییر می‌دهد. هدرها احراز هویت، content negotiation و کلیدهای idempotency را حمل می‌کنند. بدنه درخواست همان ورودی است. کد پاسخ اهمیت دارد (۴۰۱ در مقابل ۴۰۳ در مقابل ۴۲۲ – هرکدام داستان متفاوتی می‌گویند). بدنه پاسخ ساختار دارد – مسیرهای JSON که ادغام‌کننده‌ها به آن‌ها وابسته‌اند. چک uptime عادی که فقط با GET یک URL را بررسی می‌کند، بیشتر روش‌هایی را که API ممکن است از کار بیفتد از دست می‌دهد: JSON نامعتبر که همچنان ۲۰۰ را برمی‌گرداند، endpoint احراز هویت که داده اشتباه را می‌پذیرد، webhook با payload خراب، endpoint که ۲۰۰ را می‌دهد اما در داخلش "status": "error" وجود دارد.

پایش API این مشکلات را حل می‌کند و به شما کنترل کامل بر هر بخش درخواست و هر بخش اعتبارسنجی پاسخ می‌دهد. دقیقاً همان call را پیکربندی می‌کنید که ادغام‌کننده‌های شما انجام می‌دهند – همان متد، همان هدرها، همان بدنه، همان احراز هویت – و دقیقاً تعریف می‌کنید که موفقیت یعنی چه – کدهای دقیق، مقادیر زیر مسیرهای JSON، آستانه‌های زمان پاسخ، محدودیت حجم.

پیکربندی درخواست

برای هر مانیتور API در DiagnoSEO Uptime Monitoring می‌توانید پیکربندی کنید:

• متد HTTP: GET، POST، PUT، PATCH، DELETE، HEAD. همان متدی را که ادغام‌کننده‌های شما استفاده می‌کنند برگزینید.
• هدرهای اختصاصی: به‌صورت شیء JSON مثلاً {"Authorization": "Bearer eyJ...", "X-API-Version": "2024-01-15"}. استاندارد برای تست کردن OAuth، JWT، کلیدهای API و content negotiation.
• بدنه درخواست: هر رشته‌ای – JSON، XML، form-encoded یا plain text. در متدهای POST/PUT/PATCH/DELETE فرستاده می‌شود.
• Basic auth: نام کاربری و رمزعبور در صورت نیاز به محافظت endpoint.
• کدهای وضعیت مورد انتظار: لیست یا بازه. به طور پیش‌فرض ۲۰۰-۳۹۹، اما می‌توانید به یک کد خاص محدود کنید (مثلاً دقیقاً ۲۰۱ برای endpoint ایجاد) یا چند مورد خاص (مانند 200,202,204) را مجاز کنید.

بررسی، حداکثر تا ۵ ریدایرکت را دنبال می‌کند، gzip را دیکد می‌کند، Content-Type را تجزیه می‌کند تا JSON را شناسایی کند. هر بررسی کد واقعی، زمان پاسخ، اندازه و خطای احتمالی را ذخیره می‌نماید. چند مشکل متوالی (قابل تنظیم، پیش‌فرض ۲ مورد) باعث وقوع incident می‌شود.

Assertion های مسیر JSON

کدهای وضعیت به‌تنهایی برای بسیاری از APIها کافی نیستند. endpoint سلامت ممکن است ۲۰۰ را برگرداند با بدنه {"status": "degraded", "db": "down"} – هنوز ۲۰۰ است، اما شما حتماً باید از این موضوع مطلع شوید. API قیمت ممکن است ۲۰۰ را با بدنه‌ای دهد که مقدار data.price به null سقوط کرده است. API جستجو ممکن است ۲۰۰ را با results: [] برگرداند چون ایندکس از کار افتاده است.

در این موارد assertion مسیر JSON را تنظیم کنید. مسیر (مثلاً data.status یا health.checks.db) و مقدار مورد انتظار (مثلاً healthy، true یا عدد خاص) را تعیین نمایید. هر بار، پاسخ به JSON دیکد می‌شود و مقدار زیر مسیر بررسی می‌گردد. عدم تطبیق، بررسی را حتی با وضعیت HTTP صحیح هم شکست‌خورده اعلام می‌کند.

نگارش مسیر به صورت نقطه‌ای و با کروشه است: data.items[0].id کار می‌کند، همچنین users.john.email. مقدار assertion به‌صورت رشته مقایسه می‌شود؛ بنابراین "true" با بول true همخوانی دارد و اعداد هم به‌صورت عدد/رشته پذیرفته می‌شوند.

الگوهای احراز هویت

دو سبک رایج احراز هویت به طور کامل پشتیبانی می‌شوند. برای توکن‌های Bearer (OAuth، JWT، کلیدهای API) از فیلد headers استفاده کنید: {"Authorization": "Bearer eyJhbGciOi..."}. توکن در پیکربندی مانیتور قرار می‌گیرد و در هر بررسی ارسال می‌شود. برای basic auth از فیلدهای نام کاربری/رمز عبور مجزا استفاده کنید– این مقادیر ذخیره و در هدر استاندارد اضافه می‌شوند.

اگر احراز هویت به امضای درخواست یا تازه‌سازی توکن نیاز داشته باشد، کار سخت‌تر می‌شود. دو الگوی منطقی: (۱) یک توکن با عمر طولانی برای حساب سرویس تهیه کنید و آن را فقط برای پایش بگذارید، یا (۲) یک endpoint سلامت بدون احراز هویت تعریف کنید که وضعیت واقعی endpoint محافظت‌شده را منعکس نماید و همان را مانیتور کنید. اکثر APIهای مدرن حداقل یکی از این دو را دارند.

الگوهای پیشنهادی ما

• هر endpoint حیاتی یک مانیتور. لازم نیست همه را چک کنید– ۵ تا ۱۰ مورد حساس که خرابی‌شان واقعاً مشکل ایجاد می‌کند کفایت می‌کند.
• از کدهای دقیق وضعیتی استفاده کنید. دامنه پیش‌فرض ۲۰۰ تا ۳۹۹ برای API زیادی باز است. endpoint ایجاد باید دقیقاً ۲۰۱ بدهد؛ endpoint idempotent باید دقیقاً ۲۰۰ باشد؛ endpoint ورود باید دقیقاً ۲۰۰ (موفق) یا ۴۰۱ (خطای پیش‌بینی‌شده– نه ۵۰۰) دهد.
• وضعیت را با assertion JSON ترکیب کنید. با هم به مشکلات انتقال و محتوا واکنش می‌دهد. صرفاً وضعیت اِرور محتوایی را نمی‌گیرد؛ assertion تنها هم در ریدایرکت‎ها شکننده است.
• آستانه زمان پاسخ تعیین کنید. افت کارایی API نشانه زودهنگام مشکل است. مانیتور با rt_threshold_ms = 800 به شما می‌گوید API کند شده قبل از اینکه کامل قطع شود.
• بدنه کوچک باشد. هر دقیقه یک چک ارسال می‌شود– بدنه بزرگ باعث اتلاف پهنای باند طرفین می‌شود. payloadهای نمونه اما مختصر کافی‌ است.

ادغام با سایر پایش‌ها

برای هر endpoint، مانیتور API صحت درخواست را بررسی می‌کند. مانیتور ping یا پورت وضعیت فعال بودن میزبان را چک می‌کند. پایش SSL/دامنه روی همان hostname مشکلات گواهی و رجیستر را مشخص می‌کند. ساب‌مانیتور DNS، تغییر رکوردهایی که ممکن است به جعل اشاره کند را کنترل می‌کند. جمعاً چهار پایش برای یک API تصویر کاملی ایجاد می‌کند بدون تداخل زیاد.

پیکربندی

ابزار را باز کنید، روی «افزودن مانیتور» کلیک کنید، نوع «API» را انتخاب نمایید. URL را وارد کنید. بخش پیشرفته را باز کنید. متد را برگزینید، هدرها را به صورت JSON قرار دهید، در صورت نیاز بدنه را بگذارید، اگر basic auth استفاده می‌کنید آن را وارد کنید، کدهای انتظاری (مثلاً 200 یا 200,201) را بنویسید. در صورت نیاز assertion مسیر JSON اضافه کنید. بازه و آستانه اعتبار را تعیین کنید. ذخیره کنید. از دوره بعدی، مانیتور دقیقاً مانند ادغام‌کننده، API شما را فراخوانی می‌کند، پاسخ را اعتبارسنجی می‌نماید و در صورت مشاهده افت فوری اطلاع می‌دهد.

سؤالات متداول

• چه متدهای HTTP را برای پایش API می‌توانم استفاده کنم؟

  GET، POST، PUT، DELETE، PATCH و HEAD. متد را برای هر مانیتور به طور جداگانه تنظیم کنید — برای endpointهای نوشتاری (POST/PUT/PATCH)، بدنه درخواست هم می‌تواند به صورت رشته JSON یا form data پیکربندی شود.

• assertionهای JSON چگونه کار می‌کنند؟

  شما مسیر JSON (مثلاً data.status یا results[0].id) و مقدار مورد انتظار را وارد می‌کنید. مانیتور پاسخ را می‌گیرد و به JSON تبدیل می‌کند، مسیر را استخراج می‌کند و با مقدار مورد انتظار مقایسه می‌نماید. در صورت عدم تطبیق، چک با خطای «assertion failed» شکسته می‌شود و مقدار واقعی را نشان می‌دهد.

• آیا می‌توانم هدرهای احراز هویت ارسال کنم؟

  بله. هدرهای سفارشی HTTP برای هر مانیتور قابل تنظیم است—توکن Authorization، کلیدهای API، content-type و غیره. مقادیر هدرها به صورت رمزنگاری شده در پایگاه داده ذخیره می‌شوند. برای Basic Auth، فیلد اختصاصی نام کاربری/رمز عبور وجود دارد که درخواست را به شکل استاندارد امضا می‌کند.

• اگر API من با خطا ولی کد ۲۰۰ پاسخ دهد چه کنم؟

  یک الگوی رایج: API با کد HTTP 200 پاسخ می‌دهد اما بدنه این است {"status":"error"}. یک مانیتور uptime ساده فکر می‌کند همه‌چیز سالم است. با assertion JSON مثل status == "ok" این را بگیرید — assertion شکست می‌خورد و مانیتور حتی با HTTP 200 وضعیت DOWN را گزارش می‌دهد.

• چگونه با rate limit در API کنار بیایم؟

  بازه زمانی چک‌ها را طبق محدودیت API تنظیم کنید (مثلاً بازه ۵ دقیقه‌ای اگر API فقط ۱۲ فراخوانی در ساعت مجاز می‌دارد). هر بررسی مانیتور یک فراخوانی API از یک منطقه محسوب می‌شود. چک‌های چند منطقه‌ای تعداد فراخوانی را چند برابر می‌کنند — اگر API شما محدودیت سختگیرانه دارد، از مانیتور منطقه واحد استفاده کنید.