API リクエスト前に JSON を検証する

なぜ送信前に検証するのか

API リクエストが失敗すると、エラーは認証、権限、スキーマ検証、JSON の不正のいずれかを指し得ます。先に JSON ボディを検証しておけば、リクエストがサーバに届く前に丸ごと 1 種類の失敗を取り除けます。コピーした cURL コマンド、Postman のボディ、webhook サンプル、結合テストもレビューしやすくなります。

実行すべき構文チェック

厳格な JSON 検証では、ボディが JSON としてパース可能で、フォーマット済みの出力が送信意図と一致するかを確認します。

• すべての文字列とオブジェクトキーがダブルクォートを使っている
• コメントや末尾カンマがない
• 真偽値は True／False ではなく true／false
• 欠損値は undefined ではなく null かキー省略
• 最上位の値がエンドポイントの期待と一致する

ヘッダも重要

有効な JSON ボディでも、リクエストが適切な Content-Type を宣言していなければ失敗します。多くの JSON API では Content-Type: application/json を送信してください。エンドポイントが Accept も見るなら、Accept: application/json を含めて、クライアントとサーバでフォーマットの認識を一致させます。

壊れたリクエストボディ

{ userId: 42, active: True, tags: ['beta',], }

修正したリクエストボディ

{ "userId": 42, "active": true, "tags": ["beta"] }

構文検証のあとに

構文検証はあくまでパース可能であることを示すだけです。本番リクエストでは、必須フィールド、未知のフィールド、値の型、配列長、列挙値、日付文字列、ID が数値か文字列かなど、スキーマも確認してください。

デバッグのコツ

サーバが依然として有効な JSON を拒否する場合は、整形済みリクエストボディを既知の良いサンプルと比較してください。セマンティックな JSON diff はキー順を無視して本物の値の差分を見つけられるので、異なるツールが生成する payload に特に有用です。

小さな fetch + Ajv ラッパー

アプリ側に渡す前に、既知のスキーマで応答ボディを検証してください。モジュール読み込み時に 1 度コンパイルし、各呼び出しを保護します：const validate = ajv.compile(schema); const res = await fetch(url); const data = await res.json(); if (!validate(data)) throw new Error("Schema mismatch: " + ajv.errorsText(validate.errors)); return data; —— こうすれば上流の契約破壊が 5 層下に潜らず境界で表面化します。