API監視

なぜAPIには専用のモニタリングが必要なのか

APIは単なる /api/ 配下のページではありません。それは契約です。HTTPメソッドには意味があり、GET と POST でセマンティクスが変わります。ヘッダーは認証やContent Negotiation、冪等性キーなどを運びます。リクエストボディは入力です。レスポンスコードは重要です（401、403、422 などはそれぞれ異なる意味を持ちます）。レスポンスボディには構造があり、統合者はJSONパスに依存しています。単なるアップタイムチェックでURLにGETするだけでは、APIが落ちる多くの方法を見逃します：不正なJSONでも200を返したり、認証エンドポイントが間違ったデータを受け入れたり、ペイロードスキーマが壊れたwebhook、"status": "error" を内包しているのに200を返すエンドポイントなど。

APIモニタリングなら、リクエストの全部分とレスポンス検証の全要素をコントロールできます。統合者と同じリクエスト（同じメソッド、同じヘッダー、同じボディ、同じ認証）を正確に設定でき、成功条件も正確に定義できます。指定したレスポンスコード、JSONパスの値、レスポンス時間のしきい値、サイズ制限など、細かく指定可能です。

リクエストの設定

DiagnoSEO Uptime Monitoringで各APIモニターに下記を設定可能です：

• 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、プレーンテキスト）。POST/PUT/PATCH/DELETE時に送信されます。
• Basic認証: エンドポイントがその方式で保護されている場合、ユーザー名とパスワード。
• 期待するステータスコード：リストや範囲。デフォルトは200-399ですが、1つのコード（例：作成エンドポイントには201のみ）や特定の値（例：200,202,204）に絞れます。

チェックは最大5回のリダイレクトを追従し、gzip解凍、Content-Typeの解析でJSONを検出します。各チェックで実際のコード、レスポンス時間、サイズ、エラー情報を記録します。連続する複数回の障害（デフォルト2回、設定可）でインシデントが発生します。

JSONパスアサーション

多くのAPIではステータスコードだけでは不十分です。healthエンドポイントが200と返してもbodyが{"status": "degraded", "db": "down"}なら重大な問題です。価格APIが 200 でdata.priceがnullになった、検索APIが 200 なのにresults: []しか返さなくなった等も同様です。

こうした場合は、JSONパスアサーションを設定します。パス（例：data.statusやhealth.checks.db）と期待値（例：healthy、trueや特定の数字）を設定します。毎回のチェックでレスポンスがJSONとしてデコードされ、指定パスの値と比較されます。不一致なら、HTTPステータスに関わらずチェックは失敗となります。

パスの構文はドット表記とブラケット表記を組み合わせます。data.items[0].id や users.john.email などが動作します。アサートする値は文字列比較されるため、"true"はboolのtrueにも一致し、数値は文字列と数値の両方で一致します。

認証パターン

二つの主要な認証スタイルは標準で利用できます。Bearerトークン（OAuth、JWT、APIキー）の場合はヘッダー欄に{"Authorization": "Bearer eyJhbGciOi..."}を使います。トークンはモニター設定に保持され、各チェック時に送信されます。Basic認証はユーザー名/パスワード欄が用意されていて、自動的に標準ヘッダーを生成します。

もし認証がリクエストごとの署名やトークンのリフレッシュを要求する場合は、より複雑になります。二つの現実的なパターン： (1) モニタリング専用の長寿命サービスアカウント用トークンを用意、または (2) 本番APIの状態を反映する未認証のヘルスエンドポイントを用意し、そこを監視する。多くのモダンAPIではこの仕組みが既に備わっています。

おすすめのパターン

• 重要なエンドポイントごとに1つのモニター。全部を監視せず、重大な影響がある5～10個を選びましょう。
• 正確なステータスコードを使う。デフォルトの200-399は許容範囲が広すぎます。作成エンドポイントは必ず201を返すべき、冪等なものは200限定、ログインは200（成功）か401（正しく構築された失敗、500ではない）。
• ステータスとJSONアサーションの組み合わせ。両方をみることで、トランスポート層とコンテンツ層のリグレッションを検出します。ステータスだけだと内容エラーを見逃し、JSONアサーションだけだとリダイレクトに脆弱。
• レスポンスタイムのしきい値を設定。APIの劣化は依存先の問題の先行指標です。例えばrt_threshold_ms = 800なら、停止前にAPIの遅延を把握できます。
• ボディは小さく。チェックは毎分発生、ボディが大きいと両側で帯域を浪費します。最小限で代表的なペイロードで十分です。

他のモニタータイプとの併用

APIエンドポイントごとにAPIモニターは動作確認を行います。別のpingやポートモニターはホストの生存確認を行います。同一ホスト名でSSL/ドメインチェックも行うことで証明書や登録問題を検知。DNSサブモニターではレコード変更を検出し、不正な切り替えも把握できます。4つのモニターをAPIに組み合わせることで、重複せず包括的な監視が可能です。

設定方法

ツールを開き、「モニター追加」をクリックし、「API」タイプを選択します。URLを貼り付けます。「詳細設定」セクションを開き、メソッドを選択、ヘッダーはJSONで貼付、必要ならボディを入力、Basic認証使用時はユーザ/パスも設定、期待するコード（例：200、200,201）を指定します。該当する場合はJSONパスアサーションも追加します。インターバルと確認しきい値も設定。保存すれば、次のサイクルから統合者と同等の方法でAPIをコール、レスポンスを検証し、異常があれば即座にアラームを送ります。

よくある質問

• API監視で利用できるHTTPメソッドは？

  GET、POST、PUT、DELETE、PATCH、HEADが利用可能です。モニターごとにメソッドを設定してください。write系エンドポイント（POST/PUT/PATCH）はリクエストボディもJSON文字列やform dataとして設定できます。

• JSONアサーションはどのように動作しますか？

  JSONのパス（例：data.status や results[0].id）と期待値を指定します。モニターがレスポンスを取得し、JSONとしてパース、パスを抽出して期待値と比較。不一致の場合「assertion failed」エラーで実際の値が表示され、チェックは失敗となります。

• 認証用ヘッダーを送信できますか？

  はい。カスタムHTTPヘッダーはモニターごとに設定可能です — Authorizationトークン、APIキー、content-typeなどもOK。ヘッダー値はデータベースで静的に暗号化されます。Basic認証用にはユーザー名/パスワード専用欄があり、自動的に署名ヘッダーが追加されます。

• APIがエラーのペイロードで200を返した場合は？

  よくあるパターンです：APIがHTTP 200を返してもbodyは{"status":"error"}。単純なアップタイムモニターは正常だと誤解します。JSONアサーションとしてstatus == "ok"を加えることで検知できます。アサーションが失敗すればHTTPが200でもDOWNとして報告されます。

• rate limit付きAPIの監視対応は？

  APIの制限を守るため、チェック間隔に配慮してください（例：APIが1時間12回までなら5分間隔）。モニターのチェック1回は1リージョンからのAPIコール1回です。マルチリージョンの場合は呼び出し回数が複数回になるため、制限が厳しい場合はシングルリージョン利用を推奨します。